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.