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).
Carsten
On 04.09.2014 16:26, John Ralls wrote:
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
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
