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
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.
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.
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.
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
};