Hi,
As in every project, documentation of GfxPrim is lagging behind the code. Lately, I grew very fond of in-header documentation for individual functions and structures, as that is much easier to keep up to date and with just a little in-code documentation, keeping the two in sync is a hassle. How could we easily and simply do some doctext extraction?
I thought about several ways:
* Doxygen. I have no experience with it and it seems to be a bit too involved for us, but it is an option.
* Some home-grown AsciiDoc extraction from comments. Could specify the target file in the tag, these could be included by regular docs. Example:
/* SOME_SPECIAL_TAG target_file * int f(int x) * Does useful things * More asciidoc markup */ int f(int x) {return 0;}
* Some other tool (mkdoc, doxygen (parsing only) + breathe + sphinx, whatever you prefer)
The main idea is to avoid duplication, keep information together, simplify doc writing and stale data spotting and updating.
What do you think?
Tomas
Hi!
As in every project, documentation of GfxPrim is lagging behind the code. Lately, I grew very fond of in-header documentation for individual functions and structures, as that is much easier to keep up to date and with just a little in-code documentation, keeping the two in sync is a hassle.
Agreed.
How could we easily and simply do some doctext extraction?
I thought about several ways:
- Doxygen. I have no experience with it and it seems to be a bit too
involved for us, but it is an option.
That is IMHO too complex.
- Some home-grown AsciiDoc extraction from comments. Could specify the
target file in the tag, these could be included by regular docs. Example:
/* SOME_SPECIAL_TAG target_file
- int f(int x)
- Does useful things
- More asciidoc markup
*/ int f(int x) {return 0;}
- Some other tool (mkdoc, doxygen (parsing only) + breathe + sphinx,
whatever you prefer)
The main idea is to avoid duplication, keep information together, simplify doc writing and stale data spotting and updating.
What do you think?
What about kernel-doc? (see linux/Documentation/kernel-doc-nano-HOWTO.txt)
Or at least some subset of kernel-doc, the only problem I see there is how to combine the API description extracted from sources with the rest of the documentation.