The hallmark of a well-conceived SDK is the quality and range of the examples you supply with it. The examples are the starting point for the vast majority of programmers. That's where they stick their big toe in and test the water.

Most programmers will be able to scan the example code and, with some basic comments, be able to understand what they do--especially if the developers have tested the examples and seen that they actually run (not always obvious). But if you document the examples and catalog them, you add an extra dimension that sets your professional SDK apart from the rest.

In a series of pieces, I am going to show you how to do some cool things with examples using Doxygen. Today's describes how to generate automatic links from the programmer's guide in your SDK (which includes the examples, in my view) to the dry class-and-method reference side.

Before I start, I am going to assume that since you are preparing a commercial SDK, you desire to expose certain classes and methods in your headers and hide others, meaning you have made the following Doxygen configuration settings:

HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES

The meaning of these settings is that your output will show only those classes and methods that you have documented. I stress this, because links between reference and examples are only possible where you have documented the relevant classes and methods.

Now the process:

1. You don't have to keep all the examples in a single folder. Doxygen can handle examples in several sources. Personally, I prefer to keep the examples for a single library in one location, reproducing the same tree structure for the folder, relative to its parent library. It's less management overhead and eases the collaborative effort between writers, R&D and different teams within R&D.

2. Once you know where your examples are located, point to the location using the EXAMPLES_PATH configuration parameter.

That's it.

Now, the documented #includes in your example code are hyperlinked to the headers. Calls to methods are linked to the description of the classes and the methods they contain.

An extra to end: to make sure you enable all the links you can, add a compilation warning to flag the files and methods you have not documented, like this:

WARN_IF_UNDOCUMENTED = YES