Doxygen globally defined reference links

Question

In Doxygen you use reference links: define them separately and then refer to them from within the text.

/**
 * This is a documentation. Here I link [std::string] to an external web page.
 *
 * The next line is the link definition:
 *
 * [std::string]: http://en.cppreference.com/w/cpp/string/basic_string "std::string documentation"
*/

However it seems that the link definition is seen only within the documentation block. It is not seen even on other documentation blocks on the same page.

I want to define some links once, and then use them everywhere (on different pages).

Is that possible?

---

Edit (follow-up question)

In order to achieve your aim I think your best bet is to make use of the ALIAS facility.

I have managed to set it up with alias like this:

ALIASES += std_string="<a href=\"http://en.cppreference.com/w/cpp/string/basic_string\" title=\"std::string documentation\" target=\"_blank\">std::string</a> "
ALIASES += std_vector="<a href=\"http://en.cppreference.com/w/cpp/container/vector\" title=\"std::vector documentation\" target=\"_blank\">std::vector</a> "

And using it:

@std_string
@std_vector

Basically I have one alias for each link.

Can it be achieved with one alias with parameters? The use would be:

@std_ref std::string
@std_ref std::vector

The problem is that some sort of map is needed between the name (the parameter) and the link:

std::string -> http://en.cppreference.com/w/cpp/string/basic_string 
std::vector -> http://en.cppreference.com/w/cpp/container/vector

I know it can be done if one parameter would be the different part of the link, like :

@std_ref std::string string/basic_string 
@std_ref std::vector container/vector

But this is ugly, error prone and would require to check each time what the link should be.

Answer 1

It's worth noting that what you are currently using is the notation that comes only with Doxygen's support for Markdown - it's not the doxygen method for external links. The original Doxygen method is to insert an HTML link inline...

<a href="linkURL">link text</a>

... but that makes no difference to your original problem.

In order to achieve your aim I think your best bet is to make use of the ALIAS facility. The relevant manual page is here. Using them, you should be able to define an alias like std-string and have it insert the HTML link everywhere you use the alias.

ALIASES are set up in the doxyfile config file (in this section of the manual)

Answer 2

You could set up aliases manually for every C++ keyword, that you want to link to, but the better way to do this is to use the doxygen TAGFILES feature.

A tag file is basically a compact representation of the entities found in the external sources. Doxygen can both generate and read tag files.

To generate a tag file for your project, simply put the name of the tag file after the GENERATE_TAGFILE option in the configuration file.

To combine the output of one or more external projects with your own project you should specify the name of the tag files after the TAGFILES option in the configuration file.

Doxygen has a whole page dedicated to explaining how to link to external documentation

And cppreference.com has already setup a tag file for you with some basic instructions.

For the impatient:

1. Download File:cppreference-doxygen-web.tag.xml for linking directly to cppreference.com website.

2. Add this line to your Doxyfile:

   TAGFILES += "location/of/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"