Doxygen: How to link to annotated source code?

Question

I have a very simple example Main.cpp file for my library, and I have a tutorial page for it. The page looks something like this:

/**
 *  @page simpleexample Simple Example
 *
 *  This example shows basic use. It is in \ref simple_example/Main.cpp.
 *
 *  And this is the description of the example.
 */

Now what this does is it replaces the simple_example/Main.cpp reference by a link to that file documentation. I would like it to go directly to the annotated source code.

Is there a way to do it without entirely disabling the per-file documentation? I'd like to have it, but i don't like that people need to click the Main.cpp link and then also the Go to the source code of this file. link once inside. I don't care too much about how the links in the Files section behave, although I'd rather have them go to file documentation, as they do by default.

I don't want to include the source code inside the tutorial page using \example either, as it is already there in small parts which are explained individually.

Answer 1

I found in my old code that I once used main.c_source to reference the annotated source code (not the documentation!), but testing in now it doesn't work...

The best solution I have for you us a hack. Use HTML to reference the actual .html file of the annotated source.

<A HREF=main_8c_source.html><B> main.c annotated source </B></A>

From my observations Doxygen follows a standard renaming scheme. The "." is change to "_8" consistently, and "_source" is appended to reference the source code. Capitals are consistently changed to lower-case and preceded with an underscore. MyFile.c becomes _my_file_8c

You must also set CREATE_SUBDIRS = NO. If CREATE_SUBDIRS = YES then you can't really be sure which sub-directory the file will be in.

Of course as a hack, you can never be sure if it'll work in the next release. You'll always have to be double checking if it still works. Maybe suggest it to them as a Feature request...

Answer 2

Instead of redirecting your reader anywhere you could take a different approach and quote the example code in your tutorial automatically using \include or \snippet.

I agree that the two-step effect of \ref is a bit of a faff, but even having a single step to go look at the code separately from the tutorial text breaks the concentration of the reader.

Depending on the volume of code in your 'example' you could either have it inserted into the doxygen output in its entirety with \include or you could quote the key parts in your tutorial page using \snippet. The latter has the advantage that you can do it in parts interspersed by your tutorial text.

Both these have the mixed blessing that the included sample is treated as code. This means that the doxygen comments in the target file will be shown as code rather than as doxygen. This might seem undesirable but it will help make it clear which is tutorial text and which is the example file. (That said, I've only ever used snippet for just quoting real code samples in a tutorial page myself.)

Relevant Doxygen manual section here.

I note you're not wanting to use \example. My approach is slightly different (especially with \snippet), and doesn't create the 'Examples' page. This may still not be what you want, but I offer it here in case it's useful for others anyway.

Answer 3

I tried some of the possibilities and what worked for me was to create separate pages for the example code.

 /**
 *  @page simpleexample Simple Example
 *
 *  This example shows basic use. It is in \ref simple_example_main.
 *
 *  And this is the description of the example.
 *
 *  @page simple_example_main Main.cpp
 *
 *  \include simple_example/Main.cpp
 */

That would give you the output

This example shows basic use. It is in Main.cpp

Whereas I found the direct insertion of code from the \include command rather useful, as it allows you to insert more than one source per page, and have some floating text between the code files.

In order to get (any) example to work, you need to set the example path, in the example above it would probably be something like

EXAMPLE_PATH           = simple_example
EXAMPLE_PATTERNS       = *
EXAMPLE_RECURSIVE      = YES