Doxygen - is there a status?
carsten.rinke at gmx.de
Thu Sep 4 05:33:40 EDT 2014
Even though I think
- the tool (Doxygen, Wiki, plain files) is of no matter whether
documentation maintenance works out or not
- it is not possible to work offline with Wiki in contrast to git/Doxygen
I consider this mail thread closed. Wiki as the tool of choice if it is
not about API documentation.
Thanks so far for the hints.
I will come back with a first draft in Wiki, hopefully soon.
On 04.09.2014 00:28, John Ralls wrote:
> On Sep 3, 2014, at 8:07 AM, Carsten Rinke <carsten.rinke at gmx.de> wrote:
>> 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.
> We’ve tried in-source design documentation, both in plain text files and in the module descriptions in the Doxygen-docs. It wasn’t maintained. We don’t need to repeat that experiment.
> 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.
> Remember as well the discussions about our goals for the next two dev cycles. The design will change somewhat in support of those goals.
> John Ralls
More information about the gnucash-devel