Re: Doxygen Generated Code - High level structure

[John Ralls]

> On Sep 14, 2015, at 2:00 AM, Matt Graham  wrote:
> 
> You are 100% right, John – since we want multiple files in the one group we 
> need to always use addtogroup and not defgroup.
>  
> But is the idea about module structure definition and standardisation worth 
> considering? I.e. having a single file lay out the hierarchical structure of 
> the modules (using addtogroup with the sub group inside @{ and @} ). That way 
> you would just need to add the file with addtogroup and it would 
> automatically be in the module hierarchy.
>  
> Am I just overthinking things? Am I best off focusing on updating the current 
> structure? Or is this a good idea?

Matt,

I’d go with “overly optimistic”. The dependencies between modules isn’t really 
hierarchical except for QOF. There is an order of compilation but Scheme is 
used in some places in a way that allows dependencies on code that hasn’t yet 
been compiled. For example, src/engine/optiondb.c has dependencies on code in 
src/app-utils, but those dependencies are implemented in Scheme.

Another major barrier to effective use of Doxygen is that our objects are 
mostly implemented in GObject, which Doxygen doesn’t understand. It would make 
more sense to document with Gtk-doc except that we rarely use the GObject 
inheritance macros, hand-rolling inheritance with struct magic instead, and if 
there’s any use of virtualization I haven’t found it yet. We’re also 
inconsistent with function naming and Gtk-doc depends on a particular naming 
scheme to associate functions to classes. The good news is that we’re engaged 
in rewriting all of that into C++ which Doxygen does understand, so there’s 
hope for the future.

While I agree with your original statement, that a new contributor should be 
able to use the Doxygen docs to understand GnuCash’s structure, I don’t think 
that GnuCash has enough structure right now to enable that.

Regards,
John Ralls

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

RE: Doxygen Generated Code - High level structure

[Matt Graham]

You are 100% right, John – since we want multiple files in the one group we 
need to always use addtogroup and not defgroup.

But is the idea about module structure definition and standardisation worth 
considering? I.e. having a single file lay out the hierarchical structure of 
the modules (using addtogroup with the sub group inside @{ and @} ). That way 
you would just need to add the file with addtogroup and it would automatically 
be in the module hierarchy.

Am I just overthinking things? Am I best off focusing on updating the current 
structure? Or is this a good idea?

Cheers,

Matt 



From: John Ralls
Sent: Friday, 11 September 2015 12:40 PM
To: Matt Graham
Cc: gnucash-devel@gnucash.org
Subject: Re: Doxygen Generated Code - High level structure



> On Sep 10, 2015, at 7:03 PM, Matt Graham <matt_graham2...@hotmail.com> 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

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