RFC: more documentation in source files

[Martin Waitz <tali@admingilde.org>]

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: signature.asc
Description: Digital signature