I have some source code (STM32 Peripherial Lib) with existing doxygen parameters which my Doxygen Builds without Problems.
For my project I want to generate a document with all functions in each file and a specific information which I want to add to the functions. But I want to keep the old informations for another doxygen configuration.
Is that possible?
I already added this for testing:
\ifnot "SECTION_DEFINE"
<normal Doxygen Parameters from original Source Code>
\elsif "SECTION_DEFINE"
#brief Function Check TODO
\endif
With this I could deactivate the existing documentation, but I need to write this \ifnot \elsif \endif to every function.
Can I just declare a Tag and only generate the documentation for this specific tag?
Kind regards
Andi
You may create a "related page" where only your additional information will be displayed with the \xrefitem command. As \xrefitem will also create a special text section within your original documentation you may want to combine it with your original idea of using section labels and conditional documentation. To top this concept off, use aliases in order to make your documentation more readable.
Consider this example code:
/** ST documentation
* foobar
* \exclusive for andi's function \endif
*/
void andreas(void);
/** ST documentation
* foobar
* \exclusive for beni's function \endif
*/
void benjamin(void);
You may use this alias in your Doxyfile: exclusive=\if SECTION_DEFINE \xrefitem viparea "Exclusive" "VIPs".
As long as SECTION_DEFINE is not defined, the "exclusive" information will not be included in your documentation. As soon as this section is defined, a "related page" (here: viparea.html) is created in your HTML documentation containing your documented items (here: andreas and benjamin) with the exclusive paragraph behind the command. The result:
Related
Within a C project, I have to document code in dedicated .dox files and not n the C file themselves.
Excerpt from a .dox file:
/*! \page intro2 Introduction2
Sample text
\fn void foo(void)
#brief foo
foo does nothing.
*/
The documentation will appear in the "file list" under the foo.h file where my function is defined. My page will only display the "Sample text" line.
Is there any way to get the documentation in the page itself, after the "Sample text" line?
I know I can achieve that with groups. But because groups and pages are not managed the same way by Doxygen, I'd prefer getting the doc in \page.
Thanks,
/*! \page intro2 Introduction2
Sample text
foo
foo does nothing.
*/
.h For foo
\fn void foo(void)
#brief foo
Not exactly what you want but I'm thinking it will all go in a page now with link that you can click to read about the function. You might also be able to try to use \copydoc if you really want the documentation to be in the page.
While documenting a project with Doxygen, I encountered the following problem.
I have a set of example programs (demo_1.c, demo_2.c,...) which reside inside the EXAMPLE_PATH set in the Doxyfile. I created a file examples.c with the following content to include the examples:
/**
* \example demo_1.c
* \example demo_2.c
* ...
*/
After running Doxygen, an Examples page is created within the navigation as I want it but the Examples section always looks like:
Examples
--------
Here is a list of all examples:
* demo_1.c
* demo_2.c
How can I change this page? I especially want to replace the text "Here is a list of all examples:" with a larger introduction.
I already generated the doxygen layout file and the header/footer files but this does not give me any useful information.
The solution is to create a DoxygenLayout.xml file and customize it with the information you want to appear on the examples page.
Doxygen will produce a template XML file, in the current directory, from the configuration it is using currently via the following command line:
$ doxygen -l
Point Doxygen to this file by editing the Doxyfile configuration file or using the Doxywizard GUI (Expert tab -> Build -> LAYOUT_FILE) to change the LAYOUT_FILE path to your new DoxygenLayout.xml file.
I recommend doing this step explicitly instead of relying on the default behavior to pickup the DoxygenLayout.xml when it exists in the folder Doxygen is run from.
You will need to edit the <tab type="examples"> XML tag and change the existing title attribute and add an intro attribute to suit your needs. The title attribute changes both the name of the header on the page and the TAB name across the top of the HTML browser so something shorter is better.
For example:
<tab type="examples" visible="yes" title="ALI Library Examples" intro="Welcome to the fantastic set of examples I have prepared for your enjoyment."/>
Produces:
ALI Library Examples
Welcome to the fantastic set of examples I have prepared for your enjoyment.
csv-simple.tcl
Note that I could not find any information about the intro attribute in the formal Doxygen documentation. I noticed it while reading the article Adding new user Tab in the Doxygen Layout.
I use some external libraries in my project, e.g. libev.
I realize I can use markdown (or href) and put
[libev](http://software.schmorp.de/pkg/libev.html)
in my document.
However that only works in a single place, and I don't want to have to put that in the dozens of places I refer to libev.
If it's "ClientWatcher" (one of my classes), doxygen auto links to the class.
Is there some way to tell doxygen to make all occurrences of the word "libev" auto link to http://software.schmorp.de/pkg/libev.html (for example)
If you add
ALIASES += libev="libev"
to Doxygen's configuration file you can use the \libev command to generate a link, like so
/** #mainpage
* See \libev for more info.
*/
I have a doxygen header for a function as follows:
/** Some description.
#param[in] grid1 First grid
#param[in] grid2 Second grid
#pre grid1 and grid2 must be of the same dimensions
*/
I'd like grid1 and grid2 to be specially highlighted in the pre-conditions section of the generated documentations, since they are parameters. In my mind, I should be able to do something like
#pre #grid1 and #grid2 must be the same size
But this doesn't work.
Any thoughts on how to achieve this?
It would be nice if # automatically linked to the function argument definition. However, I can't see anyway of doing this in the automatic link generation section of the doxygen manual.
Having looked at the documentation HTML source it seems that parameters seem to be simply styled as strong and with the class paramname. So something like
#pre <strong class="paramname">grid1</strong> and
<strong class="paramname">grid2</strong> must be the same size.
should give you the results you want. Clearly this is overly verbose to write out each time. However, you should be able to define a custom command, say \paramname, to do this so you could just write
#pre \paramname{grid1} and \paramname{grid2} must be the same size.
Edit: This can be achieved with the configuration file alias
ALIASES += paramname{1}="<strong class="paramname">\1</strong>"
Landed here looking for the answer, but found it elsewhere.
Use \p to indicate that the next word is a function parameter.
And, of course, you can use # instead of \.
/** Some description.
#param[in] grid1 First grid
#param[in] grid2 Second grid
#pre #p grid1 and #p grid2 must be of the same dimensions
*/
See Doxygen Special Commands reference.
I made documentation for my SDK, using Doxygen. It contains the list of files, namespaces, classes, types etc. - everything that I placed as Doxygen comments in the code. Now I want to write some general information about SDK (kind of introduction), which is not related directly to any code element. I want to place this introduction on the documentation start page. How can I do this?
Have a look at the mainpage command.
Also, have a look this answer to another thread: How to include custom files in Doxygen. It states that there are three extensions which doxygen classes as additional documentation files: .dox, .txt and .doc. Files with these extensions do not appear in the file index but can be used to include additional information into your final documentation - very useful for documentation that is necessary but that is not really appropriate to include with your source code (for example, an FAQ)
So I would recommend having a mainpage.dox (or similarly named) file in your project directory to introduce you SDK. Note that inside this file you need to put one or more C/C++ style comment blocks.
As of v1.8.8 there is also the option USE_MDFILE_AS_MAINPAGE. So make sure to add your index file, e.g. README.md, to INPUT and set it as this option's value:
INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md
Note that with Doxygen release 1.8.0 you can also add Markdown formated pages. For this to work you need to create pages with a .md or .markdown extension, and add the following to the config file:
INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown
See http://www.doxygen.nl/manual/markdown.html#md_page_header for details.
Following syntax may help for adding a main page and related subpages for doxygen:
/*! \mainpage Drawing Shapes
*
* This project helps user to draw shapes.
* Currently two types of shapes can be drawn:
* - \subpage drawingRectanglePage "How to draw rectangle?"
*
* - \subpage drawingCirclePage "How to draw circle?"
*
*/
/*! \page drawingRectanglePage How to draw rectangle?
*
* Lorem ipsum dolor sit amet
*
*/
/*! \page drawingCirclePage How to draw circle?
*
* This page is about how to draw a circle.
* Following sections describe circle:
* - \ref groupCircleDefinition "Definition of Circle"
* - \ref groupCircleClass "Circle Class"
*/
Creating groups as following also help for designing pages:
/** \defgroup groupCircleDefinition Circle Definition
* A circle is a simple shape in Euclidean geometry.
* It is the set of all points in a plane that are at a given distance from a given point, the centre;
* equivalently it is the curve traced out by a point that moves so that its distance from a given point is constant.
* The distance between any of the points and the centre is called the radius.
*/
An example can be found here
Add any file in the documentation which will include your content, for example toc.h:
# mainpage Manual SDK
<hr/>
# section pageTOC Content
-# #ref Description
-# #ref License
-# #ref Item
...
And in your Doxyfile:
INPUT = toc.h \
Example (in Russian):
scale-tech.ru/luckyBackupW/doc/html/index.html (via web.archive.org)
scale-tech.ru/luckyBackupW/doc/html/toc_8h_source.html (via web.archive.org)
I tried all the above with v 1.8.13 to no avail.
What worked for me (on macOS) was to use the doxywizard->Expert tag to fill the USE_MD_FILE_AS_MAINPAGE setting.
It made the following changes to my Doxyfile:
USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT = ../README.md \
../sdk/include \
../sdk/src
Note the line termination for INPUT, I had just been using space as a separator as specified in the documentation. AFAICT this is the only change between the not-working and working version of the Doxyfile.