Writing up-to-date tutorials with Doxygen

The other day we were discussing on #plasma about KApiDox and what the Plasma team needed to write awesome documentation. Sebas and Martin were specially complaining about the fact that keeping a tutorial up-to-date was difficult because it is only text which will never be compiled for real by the writer, or not as presented.

The solution

I’d like to share the solution that Doxygen propose (adapted from the Doxygen documentation [1]):

The command is

\snippet <file-name> ( block_id )

Contrary to \include that includes a complete file as source code, this only quotes a fragment of a file. To refer to the same file you are documenting, use this as the <file-name>

For example, the putting the following command in the documentation, references a snippet in file example.cpp residing in a subdirectory which should be pointed to by EXAMPLE_PATH.

 /**
  * ....
  * A resource can easily be added with:
  * \snippet snippets/example.cpp Adding a resource
  * ...

A unique identifier refers to the snippet defined as followed

    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

The output of the snippet command is:

document->addResource(QTextDocument::ImageResource,
    QUrl("mydata://image.png"), QVariant(image));

What follows

I updated the wiki [2], and now you can continue writing awesome documentation about how to use your libraries.

You know what? The more it goes, the more I think that Techbase is slowly becoming useless… But Schhhhtttttt… this is a secret. 😀

Cheers and have fun !

Sources

[1] http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdsnippet
[2] https://community.kde.org/Guidelines_and_HOWTOs/API_Documentation#Code_Examples_in_APIDOX