Doxygen - is there a status?

[Carsten Rinke]

Oops, seems to be more left for discussion than I thought.

John,

you are absolutely right that design documentation should not reside in 
code files.
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 
src/doc/design directory).
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 
design files
- 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).
Carsten

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