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