Grantlee Gems: Making the documentation correct

Doxygen creates API documentation with ease, but the output is not exactly what you want until you spend some time deciding what you want to include in the API docs, and getting a consistent appearance throughout.

In the Grantlee documentation, there are many references to tags like “{% for %}” and variables such as “{{ my_var }}”. Those should always appear in a typewriter font, and use non-breaking spaces so that the entire tag or filter is always on one line.

Instead of writing the necessary "<tt>{%&nbsp;for&nbsp;%}</tt>" each time, it makes sense to define some macros so that in doxygen comments a simple @gr_tag{for} can be used and doxygen replaces that with the correct, consistent content.

Another piece of Doxygen magix is the use of the following lines in the Doxyfile:

PREDEFINED             = Q_QDOC TemplateImpl:Template GRANTLEE_CORE_EXPORT=
EXPAND_AS_DEFINED      = TemplateImpl

Qt documentation uses the preprocessor with the Q_QDOC define to exclude content from the public API documentation. This can be useful to hide from the documentation API that is internal, but necessarily in public headers. Additionally, GRANTLEE_CORE_EXPORT is defined to nothing when creating docs so that it does not appear in the generated documentation.

The TemplateImpl helps the documentation lie to the user. I’m sure purists would let me know it’s a bad idea, but Grantlee::Template is actually a typedef for QSharedPointer<TemplateImpl>. Consumers of Grantlee should always use Template through operator->(), but the documentation should refer to Template, not TemplateImpl.

In the header file, the Q_QDOC macro substitutes Template for TemplateImpl:

#ifdef Q_QDOC
#define TemplateImpl Template
typedef QSharedPointer<TemplateImpl> Template;

and the EXPAND_AS_DEFINED line tells Doxygen to “really substitute it”.

It is possible to customize the appearance of documentation generated by Doxygen by specifying custom header.html, footer.html etc files. Doxygen already uses Qt, although it’s an internal old version (Qt 2 perhaps?). If ported to Qt4, I could use Grantlee to change the appearance of the documentation. It’s all just part of the world domination plan…

2 Responses to “Grantlee Gems: Making the documentation correct”

  1. Adriaan de Groot Says:

    Steve, thanks for these Doxygen tips. If there is a techbase page on KDE doxygen stuff, could you add a link to this from there? Mostly as a reminder to myself when I finally pick up again. Thanks.

  2. Grantlee Gems: Subclass of a Qt type in a QVariant « Steveire’s Blog Says:

    […] Steveire’s Blog Just another weblog « Grantlee Gems: Making the documentation correct […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: