Doxygen - is there a status?

[John Ralls]

On Sep 4, 2014, at 9:11 AM, Carsten Rinke <carsten.rinke at gmx.de> wrote:

> 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).

Yes, all true. 

There are two problems, the most important of which is that since those files are off by themselves they tend to be forgotten about when documenting code changes. As I pointed out, even the module descriptions, which *are* part of the code files, aren’t getting maintained. The other problem is that Doxygen uses its own rather complicated markup (though recent versions can handle Markdown as well, which would help). That significantly increases the friction involved in maintaining those files, raising the likelihood that updating the docs is put off for later, where ‘for later’ tends toward ‘forever’.

Seriously, we’ve been down that road. If it had worked the design documents would be up to date and we wouldn’t be having this conversation.

Regards,
John Ralls