RFC: more documentation in source files

RFC: more documentation in source files

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 1613 bytes --]

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

Are there other nice and powerful source documentation systems?
Is it even worth trying to integrate parts of the documentation into
the source code?

What do you think?

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: RFC: more documentation in source files

[Greg KH]

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

Re: RFC: more documentation in source files

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 1098 bytes --]

hoi :)

On Thu, Feb 16, 2006 at 02:43:46PM -0800, Greg KH wrote:
> What's wrong with just extending kerneldoc in the ways that you feel it
> would be more powerful?

nothing wrong with that, only a lot of work ;-)

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

 * it automatically links all structures / function calls in the text
   to their detailed description.
 * it can put descriptive, structured text on one page with
   code documentation.
 * section hierarchy can be defined in the source files by assigning
   documentation blocks to "groups".
 * It's already there.

Most of these things won't be too hard to implement, but nethertheless
it will take some time.  I really don't want to reinvent the wheel.

Well, I'm not really fixed on doxygen, I just wanted to experiment
with other documentation systems to see what they can provide.
If someone can recommend a good one - fine.
If we write it ourself - fine, too.
But I don't want to start extending kernel-doc before taking a look
on alternatives.

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]