Doxygen Code Documentation

[John Ralls]

> On Aug 31, 2015, at 3:44 AM, Matt Graham <matt_graham2001 at hotmail.com> wrote:
> 
> G’day all!
> 
> 
> Whilst there is  lot of enthusiasm about documentation flowing around, I thought I’d ask a general question regarding the last type of documentation not previously mentioned: The doxygen generated documentation about how the code works (can I call it the API?).
> 
> 
> I’ve been taking my time learning and setting up git whilst browsing through doxygen and code - specifically around budgets. What I am finding is that the level of documentation generated varies greatly from file to file (and even within a file).  I generate the documentation myself from my clone of the repository.
> 
> 
> I’m very much a noob (have mainly worked with java in the past, and never with anything like gtk) - I am currently have to go line by line in the code to figure out specifically what a lot of the methods do, and how they all relate to each other to achieve the end goal. Is this usual, or is this an area where I can (and should) help out by submitting a bug report and developing a patch?

It’s pretty much the norm, even in well-documented libraries like Gtk+. The documentation covers how to use the functions but usually not how they work, and helper functions that aren’t part of the public API are generally not documented.

Some programmers, often less-experienced ones, will comment code liberally to explain what they’re doing. More experienced programmers often find this irritating because they’re fluent enough in the programming language that they can understand the code without the comments and the comments just get in the way. Those programmers prefer a brief descriptive comment only when the author finds it necessary to do something non-ideomatic.

None of which should be taken as a defense of GnuCash’s code or API documentation. A lot of the code is a turgid, unideomatic mess with several-hundred-line functions calling all over the place and sometimes flipping back and forth between Scheme and C. Writing bug reports about it won’t be helpful unless you submitting a patch, and then only if it’s a good patch that improves code readability, testability, or Doxygen documentation. If that’s the sort of work you want to take on, Welcome! If you haven’t already, get a copy of Martin Fowler’s “Refactoring” and study it: It’s the bible for fixing ugly code.

Regards,
John Ralls