Doxygen - is there a status?

classic Classic list List threaded Threaded
27 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Doxygen - is there a status?

Carsten Rinke
Hi,

Lately I was working on a bug (which I did not manage yet to fix).
During the investigations I noticed that I am still running around like
a blind chicken when starting out with a new bug.
And the reason is simple: Even though I have worked and programmed quite
a bit for GnuCash already, I still don't understand the architecture of it.

So I decided to try a top down approach instead of the buttom up in
order to learn a bit more about the 'big picture'.
And that is how I (once again) came across Doxygen.

While my first Doxygen attempts as a reader where ending up in confusion
and even more questions, I think I have now understood the idea. Still
my impression is that some high level and introducing paragraphs might
be helpful.
Currently it tells you more on how to make use of it as an author than
to actually use it as a reader.

I could start looking into ways how to improve it - but that implies
that stuff that I have in mind is really an improvement.

Therefore my first careful question:
What is the current status? Is there active work ongoing? Is it in
general agreed that additinional (even basic) work is needed in this
area? Or is everything (i.e. also conceptionally) in place as it should?

Kind regards,
Carsten
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Derek Atkins
Hi,

Carsten Rinke <[hidden email]> writes:

> Hi,
>
> Lately I was working on a bug (which I did not manage yet to fix).
> During the investigations I noticed that I am still running around
> like a blind chicken when starting out with a new bug.
> And the reason is simple: Even though I have worked and programmed
> quite a bit for GnuCash already, I still don't understand the
> architecture of it.
>
> So I decided to try a top down approach instead of the buttom up in
> order to learn a bit more about the 'big picture'.
> And that is how I (once again) came across Doxygen.
>
> While my first Doxygen attempts as a reader where ending up in
> confusion and even more questions, I think I have now understood the
> idea. Still my impression is that some high level and introducing
> paragraphs might be helpful.
> Currently it tells you more on how to make use of it as an author than
> to actually use it as a reader.
>
> I could start looking into ways how to improve it - but that implies
> that stuff that I have in mind is really an improvement.
>
> Therefore my first careful question:
> What is the current status? Is there active work ongoing? Is it in
> general agreed that additinional (even basic) work is needed in this
> area? Or is everything (i.e. also conceptionally) in place as it
> should?

I think most devs would agree that improving the Doxygen docs would be a
good thing.  I do not beleve that anyone is actively working on it.

> Kind regards,
> Carsten

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Geert Janssens
On Tuesday 02 September 2014 12:51:01 Derek Atkins wrote:

> Hi,
>
> Carsten Rinke <[hidden email]> writes:
> > Hi,
> >
> > Lately I was working on a bug (which I did not manage yet to fix).
> > During the investigations I noticed that I am still running around
> > like a blind chicken when starting out with a new bug.
> > And the reason is simple: Even though I have worked and programmed
> > quite a bit for GnuCash already, I still don't understand the
> > architecture of it.
> >
> > So I decided to try a top down approach instead of the buttom up in
> > order to learn a bit more about the 'big picture'.
> > And that is how I (once again) came across Doxygen.
> >
> > While my first Doxygen attempts as a reader where ending up in
> > confusion and even more questions, I think I have now understood the
> > idea. Still my impression is that some high level and introducing
> > paragraphs might be helpful.
> > Currently it tells you more on how to make use of it as an author
> > than to actually use it as a reader.
> >
> > I could start looking into ways how to improve it - but that implies
> > that stuff that I have in mind is really an improvement.
> >
> > Therefore my first careful question:
> > What is the current status? Is there active work ongoing? Is it in
> > general agreed that additinional (even basic) work is needed in this
> > area? Or is everything (i.e. also conceptionally) in place as it
> > should?
>
> I think most devs would agree that improving the Doxygen docs would be
> a good thing.  I do not beleve that anyone is actively working on it.

Exactly. Feel free to improve on it.

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Christian Stimming-4
In reply to this post by Carsten Rinke
Hi Carsten, which questions do you want to get answered? If you have a few, I'd like to try to write up something.

Also, our wiki contains some text about the "c API". Maybe this is of some help.

Regards, Christian

On 2. September 2014 17:10:00 MESZ, Carsten Rinke <[hidden email]> wrote:

>Hi,
>
>Lately I was working on a bug (which I did not manage yet to fix).
>During the investigations I noticed that I am still running around like
>
>a blind chicken when starting out with a new bug.
>And the reason is simple: Even though I have worked and programmed
>quite
>a bit for GnuCash already, I still don't understand the architecture of
>it.
>
>So I decided to try a top down approach instead of the buttom up in
>order to learn a bit more about the 'big picture'.
>And that is how I (once again) came across Doxygen.
>
>While my first Doxygen attempts as a reader where ending up in
>confusion
>and even more questions, I think I have now understood the idea. Still
>my impression is that some high level and introducing paragraphs might
>be helpful.
>Currently it tells you more on how to make use of it as an author than
>to actually use it as a reader.
>
>I could start looking into ways how to improve it - but that implies
>that stuff that I have in mind is really an improvement.
>
>Therefore my first careful question:
>What is the current status? Is there active work ongoing? Is it in
>general agreed that additinional (even basic) work is needed in this
>area? Or is everything (i.e. also conceptionally) in place as it
>should?
>
>Kind regards,
>Carsten
>_______________________________________________
>gnucash-devel mailing list
>[hidden email]
>https://lists.gnucash.org/mailman/listinfo/gnucash-devel

--
Sent from mobile.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Carsten Rinke
Hi all,

thanks for the quick reply.

@Christian:

I have plenty.

Big ones like "how does qof work?" and small ones like "what does xacc
actually stand for?".
Geert's hint in one of the bugzilla replies to maybe consider listening
to signals in an area that appears to me totally unrelated made me aware
that I still do not know GnuCash at all.
By accident I found the project.html file which is also quite an eye
opener, too.

BTW: I took a look at the Wiki C API page. There is also good stuff in it.
Note that the link to the entity relationship diagram returns 404 and
offers me a log in. Is that correct?

My first proposal would be to try to get Doxygen into something more
like book style - meaning leading the unaware reader to a starting point
and offer a reading thread. No idea if that is possible, but I think it
would help.

I also wonder in how far requirements can be documented with Doxygen.

But the first question is:
How am I going to do this formally?
Should I open an Enhancement Bug and feed it with patches as I go along?
Or should I iteratively attach whole tar archives with the Doxygen html
result as I would propose it for review?

Regs,
Carsten

On 02.09.2014 19:46, Christian Stimming (mobil) wrote:

> Hi Carsten, which questions do you want to get answered? If you have a
> few, I'd like to try to write up something.
>
> Also, our wiki contains some text about the "c API". Maybe this is of
> some help.
>
> Regards, Christian
>
> On 2. September 2014 17:10:00 MESZ, Carsten Rinke
> <[hidden email]> wrote:
>
>     Hi,
>
>     Lately I was working on a bug (which I did not manage yet to fix).
>     During the investigations I noticed that I am still running around like
>     a blind chicken when starting out with a new bug.
>     And the reason is simple: Even though I have worked and programmed quite
>     a bit for GnuCash already, I still don't understand the architecture of it.
>
>     So I decided to try a top down approach instead of the buttom up in
>     order to learn a bit more about the 'big picture'.
>     And that is how I (once again) came across Doxygen.
>
>     While my first Doxygen attempts as a reader where ending up in confusion
>     and even more questions, I think I have now understood the idea. Still
>     my impression is that some high level and introducing paragraphs might
>     be helpful.
>     Currently it tells you more on how to make use of it as an author than
>     to actually use it as a reader.
>
>     I could start lookin!
>       g into
>     ways how to improve it - but that implies
>     that stuff that I have in mind is really an improvement.
>
>     Therefore my first careful question:
>     What is the current status? Is there active work ongoing? Is it in
>     general agreed that additinional (even basic) work is needed in this
>     area? Or is everything (i.e. also conceptionally) in place as it should?
>
>     Kind regards,
>     Carsten
>     ------------------------------------------------------------------------
>
>     gnucash-devel mailing list
>     [hidden email]
>     https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
>
> --
> Sent from mobile.

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

John Ralls-2

On Sep 3, 2014, at 1:57 AM, Carsten Rinke <[hidden email]> wrote:

> Hi all,
>
> thanks for the quick reply.
>
> @Christian:
>
> I have plenty.
>
> Big ones like "how does qof work?" and small ones like "what does xacc actually stand for?".
> Geert's hint in one of the bugzilla replies to maybe consider listening to signals in an area that appears to me totally unrelated made me aware that I still do not know GnuCash at all.
> By accident I found the project.html file which is also quite an eye opener, too.
>
> BTW: I took a look at the Wiki C API page. There is also good stuff in it.
> Note that the link to the entity relationship diagram returns 404 and offers me a log in. Is that correct?
>
> My first proposal would be to try to get Doxygen into something more like book style - meaning leading the unaware reader to a starting point and offer a reading thread. No idea if that is possible, but I think it would help.
>
> I also wonder in how far requirements can be documented with Doxygen.
>
> But the first question is:
> How am I going to do this formally?
> Should I open an Enhancement Bug and feed it with patches as I go along?
> Or should I iteratively attach whole tar archives with the Doxygen html result as I would propose it for review?

Carsten,

You can use Doxygen to build any arbitrary web site, though it's not necessarily the best way. I used it to build the project website for wxGuiTesting http://wxguitest.sourceforge.net/ several years ago.

Just attach patches. It's easy to apply them, build the Doxygen docs, and review the results.

But maybe it's better to get replace all of the (mostly outdated) design documentation in the code base with a set of wiki pages and leave Doxygen to document only the API. That's a much easier editing and collaborative flow than Doxygen patches and I suspect that it has a better chance of being maintained going forward.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Carsten Rinke
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 ...

Regs,
Carsten


On 03.09.2014 16:00, John Ralls wrote:

> On Sep 3, 2014, at 1:57 AM, Carsten Rinke <[hidden email]> wrote:
>
>> Hi all,
>>
>> thanks for the quick reply.
>>
>> @Christian:
>>
>> I have plenty.
>>
>> Big ones like "how does qof work?" and small ones like "what does xacc actually stand for?".
>> Geert's hint in one of the bugzilla replies to maybe consider listening to signals in an area that appears to me totally unrelated made me aware that I still do not know GnuCash at all.
>> By accident I found the project.html file which is also quite an eye opener, too.
>>
>> BTW: I took a look at the Wiki C API page. There is also good stuff in it.
>> Note that the link to the entity relationship diagram returns 404 and offers me a log in. Is that correct?
>>
>> My first proposal would be to try to get Doxygen into something more like book style - meaning leading the unaware reader to a starting point and offer a reading thread. No idea if that is possible, but I think it would help.
>>
>> I also wonder in how far requirements can be documented with Doxygen.
>>
>> But the first question is:
>> How am I going to do this formally?
>> Should I open an Enhancement Bug and feed it with patches as I go along?
>> Or should I iteratively attach whole tar archives with the Doxygen html result as I would propose it for review?
> Carsten,
>
> You can use Doxygen to build any arbitrary web site, though it's not necessarily the best way. I used it to build the project website for wxGuiTesting http://wxguitest.sourceforge.net/ several years ago.
>
> Just attach patches. It's easy to apply them, build the Doxygen docs, and review the results.
>
> But maybe it's better to get replace all of the (mostly outdated) design documentation in the code base with a set of wiki pages and leave Doxygen to document only the API. That's a much easier editing and collaborative flow than Doxygen patches and I suspect that it has a better chance of being maintained going forward.
>
> Regards,
> John Ralls
>
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Derek Atkins
Carsten,

Carsten Rinke <[hidden email]> writes:

> 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.

I think John's point is that there is a big difference between the
architecture/design descriptions and the API documentation.  The latter
most certainly can (and should) be done in doxygen, but John's point was
that the former might be better served in the wiki because it's easier
to edit and frankly the design doesn't change all that frequently
(whereas code/APIs can).

> 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?

I don't understand this question.  We already do use doxygen for the
developer API documentation.  See http://code.gnucash.org/docs/HEAD/ for
the output of the nightly docs build.

So what exactly are you asking here?

> Better stop me right away before I am running in the wrong direction ...
>
> Regs,
> Carsten

-derek
--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

John Ralls-2
In reply to this post by Carsten Rinke

On Sep 3, 2014, at 7:18 AM, Carsten Rinke <[hidden email]> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: 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 <[hidden email]> 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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

John Ralls-2

On Sep 3, 2014, at 8:07 AM, Carsten Rinke <[hidden email]> wrote:

> 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.

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.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Carsten Rinke
Ok.

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.

Carsten

On 04.09.2014 00:28, John Ralls wrote:

> On Sep 3, 2014, at 8:07 AM, Carsten Rinke <[hidden email]> wrote:
>
>> 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.
> 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.
>
> Regards,
> John Ralls
>
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Frank H. Ellenberger-3
In reply to this post by John Ralls-2
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.

Just my 2¢
Frank
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Frank H. Ellenberger-3
In reply to this post by Carsten Rinke
Am 03.09.2014 um 10:57 schrieb Carsten Rinke:
> Big ones like "how does qof work?"

Good question!

> and small ones like "what does xacc actually stand for?".

Somewhere Linas Veptas told us: "There was one guy before me, he wrote
something called 'xacc' (X11-accountant) for a class project; it used
motif, not gnome; I re-wrote it several times over."

> Geert's hint in one of the bugzilla replies to maybe consider listening
> to signals in an area that appears to me totally unrelated made me aware
> that I still do not know GnuCash at all.

That might be related to "Simulate OOP in plain C via GObject".

Frank
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Geert Janssens
On Thursday 04 September 2014 13:38:48 Frank H. Ellenberger wrote:

> Am 03.09.2014 um 10:57 schrieb Carsten Rinke:
> > Big ones like "how does qof work?"
>
> Good question!
>
> > and small ones like "what does xacc actually stand for?".
>
> Somewhere Linas Veptas told us: "There was one guy before me, he wrote
> something called 'xacc' (X11-accountant) for a class project; it used
> motif, not gnome; I re-wrote it several times over."
>
> > Geert's hint in one of the bugzilla replies to maybe consider
> > listening to signals in an area that appears to me totally
> > unrelated made me aware that I still do not know GnuCash at all.
>
> That might be related to "Simulate OOP in plain C via GObject".
>
No, I think in this case my pointer was to the component manager (gnc-component-manager.h)
in GnuCash. Sorry Carsten I didn't react to this earlier.

I have now replied to on the bug [1] itself.

Geert

[1] https://bugzilla.gnome.org/show_bug.cgi?id=726674
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

John Ralls-2
In reply to this post by Frank H. Ellenberger-3

On Sep 4, 2014, at 4:13 AM, Frank H. Ellenberger <[hidden email]> 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


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

design directory, ERM; was: Doxygen - is there a status?

Frank H. Ellenberger-3
Am 04.09.2014 um 16:26 schrieb John Ralls:
> 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.

Just for completeness:
There is a bunch of texi files in src/doc/design.
 - But https://github.com/Gnucash/gnucash/commits/master/src/doc/design
shows only sparse updates after 2001.
 - And Intro starts with "This whole document is completely outdated.
Don't read this. All function names and every described structure has
changed completely. Only read this if you want to know how gnucash
looked like in 1999. This is completely outdated!"

So, I agree, mediawiki texts are today easier to maintain than texinfo
files. Perhaps we should replace the content of this directory with a
file containing pointers to the respective wiki pages.

But we should add somewhere in the doxygen linked readme files
 - A sketch of the modules, their purpose and relations
 - Explanation of namespaces gnc_, qof_, xacc_, ...

BTW:
Am 03.09.2014 um 10:57 schrieb Carsten Rinke:
> BTW: I took a look at the Wiki C API page. There is also good stuff
> in it. Note that the link to the entity relationship diagram returns
> 404 and offers me a log in. Is that correct?
John, didn't you update the ERM some time ago? But later it became
inaccessible.

Regards
Frank
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

Carsten Rinke
In reply to this post by John Ralls-2
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
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: design directory, ERM; was: Doxygen - is there a status?

John Ralls-2
In reply to this post by Frank H. Ellenberger-3

On Sep 4, 2014, at 9:04 AM, Frank H. Ellenberger <[hidden email]> wrote:

> Am 04.09.2014 um 16:26 schrieb John Ralls:
>> 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.
>
> Just for completeness:
> There is a bunch of texi files in src/doc/design.
> - But https://github.com/Gnucash/gnucash/commits/master/src/doc/design
> shows only sparse updates after 2001.
> - And Intro starts with "This whole document is completely outdated.
> Don't read this. All function names and every described structure has
> changed completely. Only read this if you want to know how gnucash
> looked like in 1999. This is completely outdated!"
>
> So, I agree, mediawiki texts are today easier to maintain than texinfo
> files. Perhaps we should replace the content of this directory with a
> file containing pointers to the respective wiki pages.
>
> But we should add somewhere in the doxygen linked readme files
> - A sketch of the modules, their purpose and relations

Better done in the master header file for each module than in separate “read me” files, but the problem is keeping them current.

> - Explanation of namespaces gnc_, qof_, xacc_, …

Better idea: Let’s get rid of all of the extra namespaces and have just one.

>
> BTW:
> Am 03.09.2014 um 10:57 schrieb Carsten Rinke:
>> BTW: I took a look at the Wiki C API page. There is also good stuff
>> in it. Note that the link to the entity relationship diagram returns
>> 404 and offers me a log in. Is that correct?
> John, didn't you update the ERM some time ago? But later it became
> inaccessible.

Yeah, I’d put it in the downloads section on Github. They dumped that service last spring and the diagram went away. I need to learn how to put images directly in the wiki.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Doxygen - is there a status?

John Ralls-2
In reply to this post by Carsten Rinke

On Sep 4, 2014, at 9:11 AM, Carsten Rinke <[hidden email]> wrote:

> 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).

Yes, all true.

There are two problems, the most important of which is that since those files are off by themselves they tend to be forgotten about when documenting code changes. As I pointed out, even the module descriptions, which *are* part of the code files, aren’t getting maintained. The other problem is that Doxygen uses its own rather complicated markup (though recent versions can handle Markdown as well, which would help). That significantly increases the friction involved in maintaining those files, raising the likelihood that updating the docs is put off for later, where ‘for later’ tends toward ‘forever’.

Seriously, we’ve been down that road. If it had worked the design documents would be up to date and we wouldn’t be having this conversation.

Regards,
John Ralls



_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
12