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.
Related
Where do libraries get the name we use in for example open BsReactNavigation?
For example, there is no module in bs-react-navigation named BsReactNavigation?
So how does reason know what we are referring to when we say open BsReactNavigation in a module?
The namespace module is generated when the namespace property in bsconfig.json is set to true. It is generated based on the name field of bsconfig.json, converted to PascalCase. That is, the first letter is capitalized, the letter following every dash is capitalized and the dashes are removed. E.g. my-wacky-library becomes MyWackyLibrary.
Some not so good documentation exists (which claims the feature is almost mandatory. It is not. While the reasoning is good, the feature is not, so most people use either just a single module or manual namespacing instead)
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've decided to document the code for my project. I found this tool Doxygen online and downloaded it.
But when I try to actually create an HTML file, it just displays the project contents and none of the special comments above the function.
I tried all types of comments - /*! ... */ , /** ... */ , ///,//!
It displays only the name of a function and its definition in the .h file, like this:
How can I fix this? How can I enable Doxygen to display the special comments too?
If I understand correctly, you are just using these special markers on code comments placed in the usual way inside functions? Check that your front-end isn't using
HIDE_IN_BODY_DOCS
If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any documentation blocks found inside the body of a function. If set to NO these blocks will be appended to the function's detailed documentation block.
The default value is: NO.
You also probably want to enable
EXTRACT_ALL
If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented, even if no documentation was available. Private class members and static file members will be hidden unless the EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
Note
This will also disable the warnings about undocumented members that are normally produced when WARNINGS is set to YES.
The default value is: NO.
I haven't specifically tested whether comments in a function body count as "documentation was available", but if you don't have parameter documentation in the doxygen format, I'd definitely turn on EXTRACT_ALL.
Doxygen by itself is a very efficient tool, but you have to learn how to use it. The key is the configuration file. The command:
doxygen -g
Will generate for you a default one in the current folder. You then need to edit it, either directly using any text editor, either through a GUI program that is name doxywizard. The default options values are usually a good start, but maybe you switched something ?
This commenting style should work:
/// define foo
#define foo 42
/// a truely efficient function
void foobar();
struct A {
int b; ///< this is something
};
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/"
When doxygen generates documentation for enum in the namespace, it adds sections of the form
<a name="a1234" doxytag="SomeNamespace::SomeEnumName"></a>
and the a1234 can be use to access the documentation for SomeNamespace::SomeEnumName as follows
http://www.path_to_documentation/namespaceSomeNamespace.html#a1234
This is done by doxygen automatically, but if one need to link to the documentation of SomeNamesace::SomeEnumName from another external page.
Is there a way one can know the a1234 name of the section? or can doxygen be configured to use a more reasonable name for the section which can then be predicted if one knows the entity being looked for? i.e. can doxygen be configured to generate names for sections to be something like
namespaceSomeNamespace.html#SomeNamespace__SomeEnumName