Doxygen: how to link to a source file written in an unsupported language?

Question

We are using Doxygen for generating HTML docs for a cross-language project. In some documentation, I would like to link to the source a of file written in a language not supported by Doxygen (actually, it's a Visual Studio T4 template).

Currently, I simply write out the file name inside the doc comment.

Including the file's extension in the Doxyfile makes the link work, but Doxygen completely misinterprets the file, and links to this misinterpreted documentation, instead of the source file, which is what I want.

If I exclude the file's extension, however, Doxygen does not take up the file at all.

Is there any Doxygen command to directly link to a file's source, instead of its documentation?

I don't really care that Doxygen is generating incorrect documentation for this file: as long as I can link directly to the file's source and not the documentation, I'll be happy enough. The docs themselves are so clearly incorrect that it does not harm that the page is generated and potentially could be found.

Any ideas?

Answer 1

I'm not sure if this is the answer you are looking for, but a few hopefully useful points follow:

• You can include blocks of source code using the \include command. From the Doxygen manual:

  \include <file-name>

  This command can be used to include a source file as a block of code. The command takes the name of an include file as an argument. Source files or directories can be specified using the EXAMPLE_PATH tag of Doxygen's configuration file.

  Using the \include command is equivalent to inserting the file into the documentation block and surrounding it with \code and \endcode commands.

• Also, from this page

  Links to files.

  All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file.

• and finally, from the Doxygen FAQ:

  11. Doxygen automatically generates a link to the class MyClass somewhere in the running text. How do I prevent that at a certain place?

  Put a % in front of the class name. Like this: %MyClass. Doxygen will then remove the % and keep the word unlinked.

From the last two points, it seems that Doxygen will automatically link to a documented file if it finds what it thinks is a filename. The % character will prevent Doxygen from doing this, but then you will need to find a way to link to the code you included with \include.

Also, see my comment to your question for how to stop Doxygen generating documentation for your Visual Studio T4 template - I presume that if you followed the suggestion in the comment then Doxygen won't automatically put a link to that file's (incorrect) documentation.

Edit: As discussed in the comments to the question, one possible solution is to create a new page for the source code and to include the source directly onto this page. For example, one could use

/*! \page src_code Visual Studio T4 Template
    \include src.tt
 */

This will include a page headed "Visual Studio T4 Template" under the "Related Pages" tab of the documentation, which can be referenced with the tag src_code (i.e. use \ref src_code to link to that page/source code).

As a final aside, if you are including C/C++ code you could enclose the \include with the \code and \endcode commands to syntax highlight the code.