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