Archive for : June, 2016

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]
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]

The output of the snippet command is:

    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 !



post image

KApiDox (or I need your input !

Hi there!

As you might know, I’m the new maintainer of KApiDox, and by that I’m more or less responisble of the website.

KApiDox used to be a script for generating the KDE Frameworks (KF5) API. This is however changing: I would like to generate all KDE APIs with this tool.

It is on its way, but before going further I need your input.

We worked with Thomas (@Colomar) on a little survey about the api. This will take less than 5 minutes of your time but help a lot. To be helpful, you don’t need to actually use the KApiDox scripts, but only the website.

Please answer the questions here:

It will help me a lot to make things better!

Cheers and have fun!