Re: DoxyGen Style Kernel API reference.

[Dennis Melentyev <dennis.melentyev@xxxxxxxxx>]

Hi Sascha and all,

2009/9/4 Sascha Wildner <saw@online.de>:
> Brian Gianforcaro schrieb:
>>
>> Depending on how nice you want the documentation to be, and how good
>> the existing documentation is.
>>
>> I'd be more than willing to put all my effort into modifying the
>> existing comments to be doxygen compliant, if this what is finally
>> decided.
>
> I wonder, how would the existing man9 manpages fit into the picture?
>
> 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.
>
> Fold the info from the manpages into the code as comments and discard man9
> entirely? That sounds like either a lot of comments would have to be added
> or (in case you should decide to take only selected portions of man9 into
> the comments) a lot of documentation would have to be discarded.
>
> Note that I'm just trying to realistically picture what would happen if we
> decide to use doxygen for kernel documentation.

Sascha, I do understand your concern. Have 25 developers next door :)

Usually, this kind of problem is only about the "process" (name it
development culture, habits, etc).

In many [not only commercial] projects some submit/commit rules are present:
0. Description of the problem it solves
1. We appreciate your patch in "diff -u blah-blah-blah" format
2. It should include man page changes (final or preliminary)
3. Codestyle should conform http://..../
4. Codestyle includes comment rules (usually handled while in review cycle).

Here, from bugzilla, for example:
http://www.bugzilla.org/docs/developer.html#intro
http://www.bugzilla.org/docs/developer.html#perl-style
http://www.bugzilla.org/docs/developer.html#apidocs

Each patch/submission always has a code review part. And almost NEVER
gets commited immediately (unless trivial changes).

Writing doxygen/javadoc-like comments is not a big effort: just
purpose of the module, function, arguments and some key notes. It is
more like helping future developers (and author himself, if coming
back to sources after another year of not touching it) with future
maintenance tasks.

Writing a man page is much more serious task. It IS a documentation,
while Doxygen is more like API description/outline.

PS. just my 0.02 UAH for what it worth.
-- 
Dennis Melentyev