Doxygen Galore

During the weekend, Vincent and I engaged in a Doxygen-galore by enabling, among many other settings, CALL_GRAPH and CALLER_GRAPH. It is graphically impressive due to the size of Patternist(although the screens Zack posted were pretty neat too).

This is the inheritance graph for FunctionCall, the base class for all function call implementations for XPath/XQuery. It is perhaps better called “the spider”.

The same graph for the Iterator class reminds a bit of a ball gown, when viewed from the side.

With TEMPLATE_RELATIONS set, the template instantiation is shown, as in Vincent’s recent work on ComparisonPlatform.

I find CALL_GRAPH and CALLER_GRAPH useful when learning code, or revisiting a large piece of code written long time ago. Iterator::cardinality() or Expression::evaluateEBV() demonstrates it nicely — one can simply surf the control flow graph. Especially, when combined with enabling the source browser, as seen in for example ValueComparison.cpp. However, it is a pity Doxygen’s control flow analysis doesn’t understand template instantiations, because the vast majority of Patternist’s objects are handled with smart pointers. For example, the call/caller graphs doesn’t generate vertexes for things like m_object->myFunction() if m_object is of a smart pointer-type.

Another practical thing, which I had no idea Doxygen was capable of, is building graphs describing file inclusions. Quite practical if one is planning a refactoring and needs to find out what needs what, in order to avoid circular inclusions, and so on.

The output of Doxygen, even without the hefty settings, is quite technical and information intensive, compared to the output of qdoc, as seen in Qt’s Assistant. An arbitrary Doxygen page is overloaded with statistics, links and what not, while Assistant is more concise — or lacking information, if one likes.

I think Doxygen’s style is useful for developers trying to tame large projects, because of its focus on implementation aspects such as where a function is defined, supplying header files, linking to the extent technically possible, and so on. However, for someone using an API as a user, most of the information provided isn’t that useful, but contributes instead to information overload. Most of this can be turned off, but I still say Assistant is a notch better for communicating an API to users, as opposed to its developers.