Monday, October 22, 2007

Doxygen rules!

I'd like to give many thanks to Dimitri van Heesch, for his excellent programming tool : the Doxygen.

I finally got to add examples to Boost Logging Lib v2. Well, you can do some amazing things with doxygen:

Say you have a file which you want to use as an example:
  • You can add the description within the example itself
  • You can reference (link to) the example's description
  • You can add the example to the "Examples" tab
  • When clicking the example in the "Examples" tab, it will show its description
  • You can even have a page which will contain the source code for all examples
To achieve the above, within the example file, you'll do this:

/**
@example your_example_name.cpp

@copydoc your_example_name

@page your_example_name your_example_name.cpp Example

... (your documentation)

*/

Then, to reference the example's description, you'll do this:

/**
...

@copydoc your_example_name

...
*/

To create a page that will contain all the examples:

/**
@page all_examples All code examples

- @ref example_1
- @ref example_2
...

\n\n\n
@section example_1 My Example 1

@include example_1_source_file.cpp
\n\n\n


\n\n\n
@section example_2 My Example 2

@include example_2_source_file.cpp
\n\n\n

...
*/

The end result is really amazing. Check it out!

No comments: