DragonFly kernel List (threaded) for 2009-09
Re: DoxyGen Style Kernel API reference.
Simon 'corecode' Schubert schrieb:
Maintaining man9 and doxygen in parallel? I think there is even less
chance that developers will care about both man9 & doxygen than taking
care of man9 alone.
I actually don't think so. Docs can be copied from the doxygen to the
man page format.
I worked on the linux source in the last days, and I have to say that
proper doxygen comments are *really* helpful for navigating in unknown code.
I strongly support Brian's enthusiasm and suggest just going forward and
doing it. Let's see how it is working out. The more documentation the
better. I don't think we should turn this into a lengthy discussion.
Who said doxygen is not helpful? I'm not against doxygen, if that is the
impression. But do you think Linux's kernel documentation is being cared
about by 2-3 people like ours is?
The questions I asked were valid questions about the future of man9 in a
doxygen scenario. Good plans that will work should have answers to
questions raised and be able to withstand a little discussion, don't you
So please let's not imply that discussion can kill good plans. On the
contrary, it helps to separate the plans based on enthusiasm only from
those that are very clear about the real work and implications involved
and yet have a good chance to work out good (which is all I care for at
this point). And please let's not place ourselves on either ends of the
opinion scale only (either totally pro or anti doxygen).
And regarding "docs can be copied from the doxygen to the man page
format": You totally missed my point. _Who_ is going to do that work or
care about it? For example, take stuff that comes in new after the
switch to doxygen. Do you think developers want to write doxygen
comments _and_ a new manual page? :)
To me, it is obvious that any attempt to maintain both man9 and doxygen
in parallel is not going to work because I can't imagine developers will
happily want to double the documentation work. Which I'm fine with btw,
one thing less to care about. Just thought I'd point it out in case
there was a different impression.