> 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
