Doxygen - is there a status?
carsten.rinke at gmx.de
Thu Sep 4 12:11:50 EDT 2014
Oops, seems to be more left for discussion than I thought.
you are absolutely right that design documentation should not reside in
That is not what I was aiming at (even though sometimes a good
implementation description can be half a design document - so there
might be a gray area).
I guess I expressed myself a bit too short:
The way I understand Doxygen, you can create html files not only from
the code files, but also from "extra files" that can live isolated from
the code files, e.g. in the gnucash/doc directory (could also be the
Doxygen can group information from those "extra files" in the mainpage
and subpages, that are either linked from within (not being visible in
the overview tree), or added to the tree in the "related pages" section.
I.e. the information from the "extra files" will show up in the main
page and the "related pages" section.
The API documentation starts with the Module section and spans over the
Data-Structures and Files sections.
My understanding is when using git as the common repository for code and
- it possible to have design documentation files for doxygen separated
from the code files
- we can make use of the git benefits (including offline work)
- cross-referencing might be easier compared to using two repositories
(git and wiki)
- the preferred editor can be used and the wiki online editor can be
avoided (personally, I am not really a friend of it)
Hope that clears up my idea a bit (which might not be a new idea).
On 04.09.2014 16:26, John Ralls wrote:
> Frank, Just like Carsten you missed the point that the *design*
> documentation doesn't and can't live in the code files and isn't part
> of writing a patch. Other than that, your suggestions are indeed
> worthwhile: The API documentation in general could stand some
> improvement, and there are plenty of modules whose documentation is
> poor or nonexistant. Your point about access to the wiki when offline
> is valid, but the design docs are generally something that one reads
> as preparation rather than when writing code. The API docs are what
> most folks consult when coding. Still, it should be possible to create
> an offline version of a wiki section if one needs it. Regards, John Ralls
More information about the gnucash-devel