Re: Doxygen Generated Code - High level structure

[John Ralls]

> On Sep 10, 2015, at 7:03 PM, Matt Graham  wrote:
> 
> G’day All,
> 
> I’ve been monitoring this list and trying to learn the structure of GNUCash 
> code for about 4 months now. I’m a bit of a noob, so it is slow going. 
> 
> I believe that code documentation (i.e. the Doxygen generated stuff) should 
> allow someone like me to quickly gain a grasp of how everything is worked and 
> linked. The detailed understanding, of course, needs to come from reviewing 
> the actual code of interest. After pouring through a lot of the current 
> doxygen generated stuff, my conclusion is that a lot of it is there, but in a 
> chaotic order. Some things are not up to date, but there is no easy way to 
> tell what needs updating and what doesn’t. Most modules (i.e. groups) do not 
> have a ‘defgroup’ definition, only ‘addtogroup’ commands for each of the 
> relevant files. This is not a problem, but the result in the past seems to be 
> that not all files have been associated with the group they need to be, and 
> creating sub-groups is somewhat inconsistent. E.g. I just added 
> gnu-budget-view.c to the Budgets group, which is called ‘budget’. I copied 
> the script from gnu-budget-view.h to get this. Additionally, we have ‘design 
> concept’ type documentation mixed into different places – e.g. the budget 
> concept document that is on the main screen under Doxygen Overviews, but 
> can’t be found with the “Budgets” module. 
> 
> What I suggest:
> 
> We have a single file in /src/doc that contains all of the defgroup commands. 
> This way it would be very simple to see and amend the structure of the 
> modules as you like. Every file that needs to has its appropriate 
> ‘addtogroup’ command within it to get it into the best point in the defgroup 
> breakdown. The very first sub-group for most modules will be a “design 
> considerations” group/file that will bring up the relevant design 
> consideration file. The next will be about the implementation (broken down 
> into sub groups if necessary, or a single ‘implementation’ group otherwise. 
> On the main page, we would keep the first section on “External 
> Documentation”, but remove “Documentation elsewhere in the source tree.”. 
> “Doxygen Overviews” would be replaced with a reference to the modules section 
> telling people to look at the appropriate module for information (because all 
> information would be there – the files, the implementation, the design 
> concepts etc). The ‘General Doxygen help” would be kept as is.
> 
> With this kind of structure, adding modules or adding files to modules 
> becomes really easy. Keeping a module up-to-date should happen automatically 
> as people update the files they are changing.
> 
> The downside is a little bit of time to change the relevant commands. I’m 
> happy to open a bug and take the lead on updating the structure to reflect 
> this. I’ll create a plan when I open the bug to ensure we aren’t left with 
> useless documentation at any point during the process.
> 
> What I am seeking is your input! Am I going down a good line? Any 
> suggestions/recommendations?

Matt,

From the Doxygen docs:
"You will get an error message when you use the same group label more than 
once. If you don't want doxygen to enforce unique labels, then you can use 
\addtogroup instead of \defgroup. It can be used exactly like \defgroup, but 
when the group has been defined already, then it silently merges the existing 
documentation with the new one.” 

IOW there’s no need to use \defgroup.

Regards,
John Ralls


___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Doxygen Generated Code - High level structure

[Matt Graham]

G’day All,

I’ve been monitoring this list and trying to learn the structure of GNUCash 
code for about 4 months now. I’m a bit of a noob, so it is slow going. 

I believe that code documentation (i.e. the Doxygen generated stuff) should 
allow someone like me to quickly gain a grasp of how everything is worked and 
linked. The detailed understanding, of course, needs to come from reviewing the 
actual code of interest. After pouring through a lot of the current doxygen 
generated stuff, my conclusion is that a lot of it is there, but in a chaotic 
order. Some things are not up to date, but there is no easy way to tell what 
needs updating and what doesn’t. Most modules (i.e. groups) do not have a 
‘defgroup’ definition, only ‘addtogroup’ commands for each of the relevant 
files. This is not a problem, but the result in the past seems to be that not 
all files have been associated with the group they need to be, and creating 
sub-groups is somewhat inconsistent. E.g. I just added gnu-budget-view.c to the 
Budgets group, which is called ‘budget’. I copied the script from 
gnu-budget-view.h to get this. Additionally, we have ‘design concept’ type 
documentation mixed into different places – e.g. the budget concept document 
that is on the main screen under Doxygen Overviews, but can’t be found with the 
“Budgets” module. 

What I suggest:

We have a single file in /src/doc that contains all of the defgroup commands. 
This way it would be very simple to see and amend the structure of the modules 
as you like. Every file that needs to has its appropriate ‘addtogroup’ command 
within it to get it into the best point in the defgroup breakdown. The very 
first sub-group for most modules will be a “design considerations” group/file 
that will bring up the relevant design consideration file. The next will be 
about the implementation (broken down into sub groups if necessary, or a single 
‘implementation’ group otherwise. On the main page, we would keep the first 
section on “External Documentation”, but remove “Documentation elsewhere in the 
source tree.”. “Doxygen Overviews” would be replaced with a reference to the 
modules section telling people to look at the appropriate module for 
information (because all information would be there – the files, the 
implementation, the design concepts etc). The ‘General Doxygen help” would be 
kept as is.

With this kind of structure, adding modules or adding files to modules becomes 
really easy. Keeping a module up-to-date should happen automatically as people 
update the files they are changing.

The downside is a little bit of time to change the relevant commands. I’m happy 
to open a bug and take the lead on updating the structure to reflect this. I’ll 
create a plan when I open the bug to ensure we aren’t left with useless 
documentation at any point during the process.

What I am seeking is your input! Am I going down a good line? Any 
suggestions/recommendations?

Cheers,

Matt
___
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel