bolov bolov - 2 months ago 19
C++ Question

Doxygen globally defined reference links

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

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)

Comments