DragonFly kernel List (threaded) for 2009-09
DragonFly BSD
DragonFly kernel List (threaded) for 2009-09
[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]

Re: DoxyGen Style Kernel API reference.

To: Simon 'corecode' Schubert <corecode@xxxxxxxxxxxx>
From: Sascha Wildner <saw@xxxxxxxxx>
Date: Sat, 05 Sep 2009 16:32:30 +0200

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 think?

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.



[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]