RFC: more documentation in source files
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?
Signature · 1 line
Martin Waitz
Quoted 21 lines · Martin Waitz
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 fromDocumentation/driver-model/intodrivers/base/*.cand changed some kernel-doc comments to Doxygen comments.
Quoted 16 lines
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
hoi :)
Quoted 2 lines · Greg KH
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 ;-)
Quoted 2 lines
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.
Signature · 1 line
Martin Waitz