Doxygen - is there a status?

[Carsten Rinke]

Hi,

what I (currently) have in mind is to use the Doxygen main page and 
related pages for pulling together all sort of conceptional design info 
I can find (by looking at the wiki, at html files from the tar ball, 
comments in the code, hints from this mailing list, whatever).
So this would make up files used and written only for documentation, no 
mix with code (like the currently available doxygen_mainpage.c file). 
Here I would also like to add some pictures.

The rest (Modules, Data Structures, Files, etc.) should come directly 
from the source files, basically as is.
Some source files contain quite a good implementation description.
Here the improvement that I currently see is to get the Modules in a 
more 'obvious' order, but I have not that this through yet, so I might 
actually skip this.

Then I would think about whether the design descriptions could be 
brought into the source files tree, so they end up as more detailed 
descriptions in Doxygen. Again, not fully thought through. I am still in 
brainstorming mode to find a way that makes access to the design easier 
for those not having worked as a professional designers and programmers.

Something like this.

Basically this would remove the need to have a wiki as design 
documentation source.
The opposite strategy is to not put any design info at all into Doxygen 
and do it all in Wiki which I do not prefer if everything could done in 
one viewer.

That is the where you should stop me.

Carsten


On 03.09.2014 16:37, John Ralls wrote:
> 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
>
>