Consolidating Documentation Fragments on one page - doxygen

I would like to consolidate documentation fragments on one page.
My use case is I have two different source modules where I want to put a doxygen fragment. Then in a third source module I want to put a #page that references the fragments.
My hope is that when the doc is generated I will see those 5 fragments consolidated onto one .html page.
The page/subpage system does not work because that just puts links on a page to the documentation fragments. I want the fragments consolidated onto one page.
This is the first .c file:
/*! #setfrag FRAG1
** this is some text for fragment 1
*/
This is a second file:
/*! #setfrag FRAG2
** This is some text for fragment 2.
*/
This is a third file:
/*! #page SOMEPAGE Page demonstrates consolidating fragments.
** #getfrag FRAG1
** #getfrag FRAG2
*/

I'm not sure if I understood your question right, but this should be exactly what grouping does. You can define a "group" using the tag #defgroup groupname description and then add the fragments to the group using the tag #addtogroup groupname.
Then you would define your group in any file (e.g. you could create a seperate file "groups.dox"):
/**
* #defgroup myGroup My Group
* #brief A brief description of \"My Group\"
* #details A more detailed description of \"My Group\".
*/
Them you can add fragments or complete files to this group by adding the following to the files:
/**
* #addtogroup myGroup
* #{
*/
// any contents you want to add to the group
/**
* #}
*/
This results in a tab called "Modules" where each group is listed as a "Module" with its own page. If you want to add the whole file documentation to the group ensure that you also enclose the #file tag with the #{ and #} tags.

Related

doxygen: nest subpage titles inside section title in treeview

I would like to customise the appearance of the navigation tree column to have subpages' title nested inside the section's title they are referenced in. For instance, this simple example
/**
* #mainpage Mainpage
* #section section_1 Section 1
* Description of section 1
*
* #section section_2 Section 2
* Section 2 is composed of the following modules:
* - #subpage module_1_page
* - #subpage module_2_page
*/
/**
* #page module_1_page Module 1
* Module 1 description
*/
/**
* #page module_2_page Module 2
* Module 2 description
*/
results in the following output:
What I would like to achieve is something like this (I manually edited the HTML result):
I had a look at the page Customizing the output of the Doxygen documentation, but I was not able to find anything that seems helpful in this case.
Also, I had a look at grouping as an alternative to pages, but it does not really fit my purposes - I use groups for actual APIs documentation, whereas I'd like to use pages for more "descriptive" documentation.
Is this possible to achieve? For the sake of completeness, I am using doxygen v1.8.13.

Create a custom index in doxygen

I would like create a index of ".h" files in my doxygen-ed project in addition of the default index.
Is there a way to do this automatically ?
I have do this by adding a \addtogroup in every headers like this :
/** \addtogroup Headers
* - oge-mutex.h
* \copybrief oge-mutex.h
*/
This will create a page with a list of all marked headers and her brief description.

Doxygen: extract specific doxygen defines into separate documentaion

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:

Doxygen displaying documentation within \page

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.

How to make an introduction page with Doxygen

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.