Doxygen - is there a status?

[John Ralls]

On Sep 4, 2014, at 4:13 AM, Frank H. Ellenberger <frank.h.ellenberger at gmail.com> wrote:

> Hi,
> 
> I have a different view:
> 
> Am 04.09.2014 um 00:28 schrieb John Ralls:
>> We’ve tried in-source design documentation, both in plain text files
>> and in the module descriptions in the Doxygen-docs.
> 
> should read "Only few of us ..." - perhaps others are unsure about the how?
> 
>> It wasn’t maintained.
> Perhaps we should
> * not accept patches without the respective doxygen entries.
> * improve http://wiki.gnucash.org/wiki/Doxygen
> ** Which parts should have and which not doxygen entries,
> ** Which elements/styles do we use, which not, ...
> * reference it in http://wiki.gnucash.org/wiki/CodingStandard ?
> 
>> We don’t need to repeat that experiment.
> 
> It was never made with full force.
> 
>> Let’s try moving it all to the wiki instead, and where appropriate
>> link the API documentation. That has the added advantage that you can
>> update the design docs directly without having to propose patches.
>> 
>> Both the Doxygen docs and the wiki are viewable in one viewer: The
>> web browser. They can even link to each other when that’s
>> appropriate.
> 
> But not if I am isolated from code.gnucash.org. With one make command I
> have the doxygen files, but without a route (code down, provider
> problem, no phone net, ...) I have no wiki.
> 
>> Remember as well the discussions about our goals for the next two dev
>> cycles. The design will change somewhat in support of those goals.
>> 
> 
> IIRC from my own experience, a newby sees something which would be
> simple to improve, but it needs too much time to find the right file. So
> the overview and probably some cross reference needs improvement -
> different types of references should be much easier to maintain in
> doxygen than in a wiki.
> 
> Surely only few global files like
> http://wiki.gnucash.org/wiki/Dependencies => README.dependencies can be
> kept sychronous.

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