Doxygen Generated Code - High level structure

Matt Graham matt_graham2001 at hotmail.com
Thu Sep 10 22:03:52 EDT 2015


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


More information about the gnucash-devel mailing list