Re: RFC: more documentation in source files

[Greg KH <greg@kroah.com>]

On Thu, Feb 16, 2006 at 10:40:34PM +0100, Martin Waitz wrote:
> hoi :)
> 
> I'd like to move some of the documentation which sleeps in Documentation/
> into the .c files that contain the documented code in the hope that
> somebody who changes the code also changes the documentation in one go.
> 
> We already have a system to generate documentation from the .c files,
> so I made a little experiment and tried to use kernel-doc to build
> the complete documentation after all text from the template files got
> moved to the source files.
> I haven't really succeeded in generating valid docbook output from
> the source files alone. So I looked at other tools to do this job.
> 
> Doxygen looks fairly promising and is even already used by some
> kernel files.
> You can get a first impression of Doxygen output here:
> http://tali.admingilde.org/linux-doxygen/html/group__drivermodel.html
> For these pages I stuffed some files from Documentation/driver-model/
> into drivers/base/*.c and changed some kernel-doc comments to Doxygen
> comments.
> 
> However there are several drawbacks when using Doxygen:
>  * it doesn't generate DocBook
>  * the source markup does not look as nice as kernel-doc:
> 	/**
> 	 * foo - short description
> 	 * @param1: parameter description
> 	 * long description
> 	 */
> 	gets:
> 	/**
> 	 * short description.
> 	 * \param param1 parameter description.
> 	 * long description
> 	 */
>    but on the other side it's much more powerful, too.
>  * we need some transition strategy

What's wrong with just extending kerneldoc in the ways that you feel it
would be more powerful?

What specifically do you feel is lacking in kerneldoc that doxygen
provides?

thanks,

greg k-h