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.ri...@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
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
