We have our own \mainpage section defined for our Doxygen build and I want to have a link as part of this to the auto-generated Class Index page (classes.html) and Namespace List top level page (namespaces.html).
I've tried things like \ref namespaces and \ref classes but that doesn't work. Any idea what the magic tag is?
There are no symbolic names at the moment to refer to the overview pages.
If it is for HTML only you can do
Link to the class index
If you need something for other output formats as well, you can wrap the above in \htmlonly...\endhtmlonly and do something similar for the other output formats.
Related
All class name instanced«s in a class' documentation are linking to itself. Is there an option to prevent this?
This is particularly relevant when I have several classes with similar names and need to navigate through their documentation.
I'm using Doxygen 1.8.13 to document c++ project.
I have not tested it yet, but according to the documentation of Doxygen:
All words in the documentation that correspond to a documented class
and contain at least one non-lower case character will automatically
be replaced by a link to the page containing the documentation of the
class. If you want to prevent that a word that corresponds to a
documented class is replaced by a link you should put a % in front of
the word. To link to an all lower case symbol, use \ref.
I am trying to follow these doxygen examples, but nothing shows up. I run
doxygen Doxyfile, and check the index.html file, but nothing is there. Only stuff that is in my mainpage.dox file, nothing to do with any classes. Ideally I'd have a class list, with this particular class I documented in it.
Perhaps it's my file structure. Does Doxygen just recurisvely search the root directory, or does it look for files with a special tag?
I found that I had to use both the #class parameter, as well as a brief description of the Class before that class was listed in the Class section of my generated documentation.
I'm trying to get doxygen 1.8.7 to include detailed descriptions in the HTML output. For example, given the following file:
/** \file iniparse.h */
namespace ini {
/** \brief A brief description.
*
* A longer description.
*/
inline void parse() {}
}
My HTML for iniparse.h contains an entry for ini::parse, with text "A brief description. More..." The "More..." part is a broken link to a non-existent anchor in the same page. And the text "A longer description" appears nowhere in the generated HTML.
If I get rid of the namespace and just define a function parse (i.e., ::parse) outside of any namespace, things work fine. Can someone tell me how to get the same behavior inside a namespace? Thanks.
Turns out this problem is caused by a combination of three things. First, a plain old bug in doxygen:
https://bugzilla.gnome.org/show_bug.cgi?id=745481
Second, even with the bug fix, you need to generate the namespaces page or you still get broken links. Hence, you need to have SHOW_NAMESPACES = YES in your Doxyfile.
Third, unless you have EXTRACT_ALL = YES, you have to make sure the namespace itself is documented by attaching a Doxygen comment to it. So you need:
//! The ini namespace
namespace ini {
...
}
On one hand maybe it makes sense to require namespaces to be documented if you want documentation for their contents. However, it's weird that doxygen shows the first part of the documentation even without the namespace documentation. So I would argue this is still kind of a bug, but at least I know how to work around it now.
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="std::string "
ALIASES += std_vector="std::vector "
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.
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...
link text
... 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)
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:
Download File:cppreference-doxygen-web.tag.xml for linking directly to cppreference.com website.
Add this line to your Doxyfile:
TAGFILES += "location/of/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
I'm trying to document a class embedded within a namespace, and I would like to give example usage. I have the examples written and included, and they show up in the examples tab. However, they are not referenced in the class itself. For instance, from the code on this page, their Doxygen command is written as:
/** \example example_test.cpp
* This is an example of how to use the Test class.
* More details about this example.
*/
It seems that Doxygen parses the command and the file and recognizes that the Test class is referenced. That doesn't seem to be happening for me. This feature isn't very well documented, and is almost impossible to Google for.
This is the general layout of my code:
namespace exampleSpace
{
///Doxygen documentation
class exampleClass {};
///#example example1.cpp
/// example1 description
///#example example2.cpp
/// example2 description
}
The example descriptions name the class, as does the one in the official documentation. However, Doxygen seems to recognize theirs and not mine.
My example code is complete and compiles/runs correctly.
So where is the correct place to put these commands so Doxygen knows that they are examples for this specific class?
EDIT: It seems Doxygen is actually parsing the source, as it successfully links to the class and any member functions within the code. However, the class page itself doesn't link to the files.
I have used \snippet for that. You refer to another file, in that file you can surround a code block with [mytag] areas. Those are then displayed where \snippet is used.
See also https://stackoverflow.com/a/35759133/356726 and https://stackoverflow.com/a/16034375/356726
Just a guess at this point, but I bet Doxygen is not matching things up because of the namespace.
Some ideas to make the linking happen:
Explicitly qualify the namespace of all names in the examples
Put the code in the examples in the namespace