Doxygen - is there a status?

[John Ralls]

On Sep 3, 2014, at 7:18 AM, Carsten Rinke <carsten.rinke at gmx.de> wrote:

> John,
> 
> actually I am in favor of Doxygen because then the design documentation and the implementation is put into one place, and it should be part of the designers work to maintain both, ideally in the same file. If using wiki, then you have to maintain two places. Not to forget the automated stuff that Doxygen is doing.
> 
> And as a side effect you get browsable code.
> 
> Is there / Has there been a discussion/decision about whether to use or not to use Doxygen?
> 
> Better stop me right away before I am running in the wrong direction ...

Carsten,

The comments that go in the code files document API, ideally with an overview of that file’s contents, each class’s responsibilities, and then each function’s parameters and return value. Maintaining that is indeed part of maintaining the code.

Then there’s the overall design documentation. There’s no code file that applies to all of e.g src/engine or src/gnome-utils; QOF has qof.h, but over time src/libqof/qof has accumulated stuff that isn’t really part of QOF. We have instead src/doc, which hasn’t been touched in many years. Regardless of what we might like to enforce, I don’t foresee any real change in that behavior, and in any case the observation that one has to maintain two places holds true for code and src/doc. 

The “automated stuff” that Doxygen does is convert jdoc markup in files it’s pointed at to HTML. The wiki does exactly the same stuff, just with different (and more familiar to most people) markup.

There hasn’t been a discussion about using Doxygen in *my* memory, but I’ve only been on the project for 5 years. That’s probably long enough that it’s worth revisiting now.

Regards,
John Ralls