Re: DoxyGen Style Kernel API reference.

[Sascha Wildner <saw@xxxxxxxxx>]

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.

Sascha

--
http://yoyodyne.ath.cx