Re: GSoC proposal: NetBSD Kernel Documentation Management Toolchain

[der Mouse <mouse%Rodents-Montreal.ORG@localhost>]

>> [...] 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                mouse%rodents-montreal.org@localhost
/ \ Email!           7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B