I'm trying to have doxygen show a brief summary of the function in `Files->File Members->Functions'
For Example:
I want this:
Box_The_Function_Name() : doxygen_c.h
to look like this
Box_The_Function_Name() : doxygen_c.h : brief explanation
Doxygen does this automatically for structs but not functions.
Any ideas ?
Doxygen does this automatically for structs but not functions.
No, it doesn't. Classes/types are not represented on this page at all, but instead in the list of classes, which is a completely different page with a different paradigm.
On this page, where functions, variables and defines are listed, the nature of translation units means that the same name could be found in multiple files, e.g.:
Box_The_Function_Name() : A.h , B.h, C.h
Here's a real-world example from my commercial project (don't tell anyone):
parse_options() : debug-register-reader.cpp , main.cpp , metrics-converter.cpp , debug-register-writer.cpp
The function parse_options() in each file is different, and may have a different summary text. It would not be very user-friendly if Doxygen tried to cram each summary text into a list here.
So, no, you can't do this.
However, you can simply click on the filename to go to the documentation for the function as found in that file.
Related
Minimal example
I wrote a program in org-mode using literate programming technique with :noweb extension(?). Typical piece of code looks like this:
* Section
In order to do foo with bar, we define a function ~do_foo~, which initializes object of a class ~BarParser~ with a value of parameter of the type ~bar_t~.
#+name: section_function_blockname
#+begin_src cpp
void do_foo
( bar_t bar
, <<additional_parameter_to_do_foo>>
) {
BarParser barParser(bar);
<<section_function_do_fooBody>>
}
#+end_src
The function will require additional parameter for the purposes of the /FizzBazz/ module. We will discuss them in a [[*Decoding FizzBazz messages][later_section]].
Entire content of the program is stored in a single file, which at the top has #+SETUP: theme-readtheorg.setup. The setup file is not the problem, because the HTML generates correctly, only with not the content I want.
Problem
To generate the code, I use (org-babel-tangle). This produces all the files I'd expect for all the blocks with :tangle parameter. The files have the content I expect them to have and code compiles and runs the way it should.
To generate the documentation I'd like to publish along the code, I use (org-html-export-to-html). What I expected to happen was that either:
the <<tags>> will get substituted with their expected value, which wouldn't be ideal but at least acceptable, or
the <<tags>> will be left untouched the way they are presented,when editing the org-file with Emacs.
However the output to (org-html-export-to-html) is quite different and unexpected - all the <<tags>> are replaced with a newline character. This leaves me with all the code blocks having incorrect content that cannot be understood without either looking at the generated code or original org-file which completely defeats the purpose of the documentation being in the separate file. I cannot force everyone I work with to switch to Emacs to let them browse the documentation!
Question
As stated above, the problem is with noweb <> being procesed by some call inside (org-html-export-to-html). The question I have regarding this issue is:
How can I force (org-html-export-to-html) to leave the contents of source blocks as they are, without stripping away the noweb <<tags>>?
IIUC, you need to specify an appropriate :noweb header. Try this:
#+begin_src cpp :noweb no-export
and refer to the noweb section in the manual for other values and more details.
I'm using sphinx to document a C++ project, in which there are various pages that document a class. In these I've used :noindex: for the class methods, since otherwise they clutter the whole project Index page.
.. cpp:function:: void foo(int a)
:noindex:
However, one of the differences this also makes is that I cannot create local in-page links. Eg., in the doc body for a different method:
The first argument is the same as that to :cpp:func:`foo`.
Without :noindex: on foo(), this link works. With it, no error is generated and there is a link, but it's dead/useless/goes nowhere.
How can I get around this?
Manual creation of local links is fairly simple in reStructuredText:
.. _`foo()`
.. cpp:function:: void foo(int a)
:noindex:
Defines the target without changing the appearance of anything. To link it,
The first argument is the same as that to `foo()`_.
Notice the location of the underscore is front to back. The ticks are needed if you want to include the parentheses; if the label is plain alphanumeric they can be discarded.
A few shortcomings:
You can't wrap this in mark-up, eg., to monospace or emphasize the link text.
There doesn't seem to be a way to substitute the link text.
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.
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