>> [...] doxygen [...] > As regards doxygen: ow. Quite.
> Have you ever actually tried to run a nontrivial part of the NetBSD > tree through doxygen? No. I have, however, tried to use doxygen-generated "documentation" for various other projects (this from the days when I was hacking on some Android code). The best I ever saw it get was mediocre. At the bad end, I had to go look at the code to figure out what it was even _trying_ to say. > It does not actually understand C well enough to deal with very > common things in our tree such as the queue.h macros. Nor plenty of other things. I don't recall details, but I recall there was something about on the order of thinking there was a struct member named "int". An officemate of mine (far more of a "Linux and all things GNUish" fan than I) pointing out that I shouldn't blame the tool for broken uses of it - but when you see enough broken uses and no good uses, it's hard to avoid seeing the tool as, at the very least, to be censured for encouraging brokenness. While it wouldn't, per se, be a bad thing to consider doxygen-generated documentation, it quite possibly would be if it encourages sloppiness such as I saw. "Oh, I don't have to bother writing good comments, doxygen will deal with generating documentation" - I can't know whether that was actually the mindset, but it would have been consistent with what I saw. And I think introducing something that encourages - or brings with it - anything like that mindset would be a disaster in the making. (Not that NetBSD doesn't have plenty of those, but that's no reason to add one more.) /~\ The ASCII Mouse \ / Ribbon Campaign X Against HTML [email protected] / \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B
