I'm using Doxygen to document a project. In one file, I have a bunch of public functions that I want to put in a group. I do this as follows:
/**
#file myFile.c
#brief This is a file. It has stuff.
*/
/**
#defgroup my_group Group with myFile.c stuff
#{
*/
//CODE & STUFF WITH DOCUMENTATION
/**
#}
*/
The issue is that the LaTeX output contains all of the documentation here twice; once in the "Module Documentation" section and again in the "File Documentation" section. This amounts to maybe 25 pages of purely duplicate stuff in my end PDF file (generated from LaTeX).
An ideal fix would be to have the File Documentation for myFile.c say "See #ref my_group" or something like that. Is there a way to accomplish this in Doxygen?
Acceptable solution found:
Create a Doxygen layout XML file and configure Doxygen to use it (instructions)
Open the XML file; find the <group> tag; comment out the <detaileddescription> and <memberdef> sections
This resulted in only the list of members being produced in the "Module Documentation," with hyperlinks to the full member documentation within the "File Documentation" section in the LaTeX/PDF output. The HTML output already functioned this way, so it was not significantly changed.
Related
I've got a mainpage using a HTML table that I only want to be included in the HTML output of doxygen. It should not be included in the other outputs (currently only LaTeX).
Since that mainpage uses doxygen commands like \ref and \mainpage itself, the \htmlonly tag is unfortunately not an option.
Is there a way to limit a markup file to certain outputs only?
As suggested, I ended up running doxygen twice, once for HTML output and once for LaTeX output. This gives me the flexibility to change other settings for different outputs as well, which is also something I was looking at.
So the dox file for my mainpage now looks like
/**
\if MySpecialFlagForHTMLOnly
\mainpage notitle
...
\endif
**/
My default doxyfile has GENERATE_HTML = YES and GENERATE_LATEX = NO. It also defines MySpecialFlagForHTMLOnly in ENABLED_SECTIONS.
Now for a second automated run, I change both GENERATE_HTML and GENERATE_LATEX and clear MySpecialFlagForHTMLOnly from ENABLED_SECTIONS.
I have a rather complex project and I want to document it using doxygen.
I have no problem documenting the code and I also managed to have a nice front-page using a custom README.md file coupled with "USE_MDFILE_AS_MAINPAGE = README.md" directive in Doxyfile.
I defined several groups (#defgroup) which show up as "Modules" in my documentation.
I would like to add a "main page" to each of the group giving general information, beside the customary function/variable/type documentation.
I tried adding custom MODULENAME.md files coupled with matching #includedoc MODULENAME.md entries in group definition, it seem to work (I see several lines like: "Generating docs for page md_mcu_noitr_coro_README..."), but I cannot find if and where the page is linked (I expected to see it in the "Detailed Description" for the module, as it happens if I put some documentation inline where I put the "#includedoc" directive.
a snippet of one of my modules is:
/**
* #file coro.h
* #brief definition of coroutine implementing functions.
*
* #date: Feb 8, 2018
* #author: myself
*
* #defgroup coro "Coroutine implementation in plain 'C'."
*
* #includedoc mcu_noitr/coro/README.md
* #{
*
*/
What am I doing wrong?
Note: it is also a bit surprising I need to put the whole path from where my Doxyfile is, otherwise doxygen won't find it even if it's right beside the file containing the #includedoc command.
I also came across the problem that included files with Markdown formatted text via \includedoc or \include{doc} does not result in correctly interpreted Markdown. Note that I included Markdown files from other Markdown files. My work-around was to use the C pre-processor (cpp) - which is widely available - on Markdown files and use it's #include directive. You could of course use a true general text processor such as M4 as suggested in the cpp man page. Set FILTER_PATTERNS in Doxyfile as:
FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"
You'll need the -P option to avoid it outputting line markers, which confuses Doxygen. -traditional-cpp was needed to avoid cpp eating white space that is important for the correct interpretation of Markdown. Don't use single quotes as this results in an error when Doxygen calls cpp via sh.
Then in my Markdown main page:
Main Page {#mainpage}
==========
Blah blah blah.
#include "other.md"
Using FILTER_PATTERNS instead of INPUT_FILTER avoids the problem about not being allowed to add or remove lines.
I have my markdown files in the same directory, I would guess that if they are located in different places you could tell cpp about it via -I, which would address your expectations about include paths on the issue you filed.
At the moment doxygen does not consider the fact that commands like \includedoc can contain markdown code. At the moment the only possibility would be to write a filter, see configuration parateter INPUT_FILTER in the doxygen configuration file, (not tested!) to replace the \includedoc` with the code of that file.
I would like to add descriptions for each folder as noted in the picture:
Is this possible?
You can document folders with the \dir or #dir command
http://www.doxygen.nl/manual/commands.html#cmddir
The documentation on this is not great. But I did already go through the time to figure out how it works. In any source file you want you can add the documentation for the folder (or even create a specific file for the folder's documentation).
In your case
/** \dir workspace
* \brief "Folder description that shows up where you want"
* \details More details to be displayed on the folder's page.
*/
/** \dir workspace/SWTtutotial
* \brief "Folder description that shows up where you want"
* \details More details to be displayed on the folder's page.
*/
Note... watch your spelling of "tutorial" ;)
A side note: I noticed a bug related to folders names having a common suffix. I get the following warning:
file.cpp:180: warning: \dir command matches multiple directories.
Applying the command for directory /sources/
Ignoring the command for directory /testsources/
The comment at line 180 causing this warning
/**
* \dir "sources"
* \details Adding details later 3...
*/ //works but complains about also matching "testsources". Doxygen Bug?
I fixed it by using \dir /sources instead of the quotes. This is ok if the path does not have spaces in it... otherwise we need a bug fix.
I have a framework which I am extending. There are some source folders which contain quite a lot of files and I want to document my work (especially those files which come from me) using doxygen.
Any file I am documenting contians a header:
/**
* #file my_file.c
* #author Stefan F.
* #date 28.05.2014
*
* #brief This file is awesome!
*/
Can I somehow tell doxygen to NOT include files without such a header?
I have already set
EXTRACT_ALL = NO
Files which don't have a doxygen header are not generated but they are still listed in the file list.
Does anyone know how to configure doxygen to get that behavior?
I'm not aware of any part of Doxygen that will do exactly what you are looking for, however, the simplest way to achieve your aim is simply to only list the files you want doxygenning in the doxyfile INPUT line.
INPUT = my_file_1.cpp myfile2.cpp moreofmyfiles/etc.cpp
(Beware it's a space separated list.)
Depending on your folder structure you may need to set RECURSIVE = NO
If it's your own personal project and you can name your file myname_file.cpp you could use FILE_PATTERNS to select only those files beginning "myname_* - but I'm expecting that's not a viable set of circumstances.
So I'm new to using Doxygen and I was able to get it to work smoothly. I was able to document my classes and structs and it generates the HTML files perfectly. The issue I'm running into is it won't parse my main.cpp file. All the classes and structs have their own .h and .cpp files and they process fine. How do I get Doxygen to make the documentation for main.cpp? It doesn't have a .h file as this is where the program starts and ends. I wouldn't even know what to put in the .h file for main. I'm using Doxywizard in Windows.
Edit:
I put this in main and it generates a main page:
/**
#mainpage
This is a test application.
#author Alex
#date 10/21/2010
#version 1.0
*/
But then farther down the file where the function prototypes are I have this and it doesn't get parsed:
/**
#brief Error handler for the PDF writer.
It does nothing. It just has to exist.
*/
void error_handler (HPDF_STATUS error_no,
HPDF_STATUS detail_no,
void *user_data)
{
}
I put this at the top of main.cpp and it worked. Go figure.
/**
#file main.cpp
*/
If INPUT and FILE_PATTERNS are empty, it should search for *.cpp files (and many other patterns) in the current directory. (This from the doxygen manual.)
Since yours are empty, I expect one of two things is going on if you're not getting main.cpp documentation:
main.cpp is not in the current directory. To rule this out, make sure you're running doxygen from the same directory as both your config file and main.cpp.
There is a syntax error in your main.cpp documentation. These can be tricky to spot, as doxygen doesn't generally abort when it encounters an error - instead it just skips ahead. If this is the problem, comb through doxygen's output when you generate your docs line by line.
If neither of these ideas solve your problem, we might need more information. Output of ls -R, output of the doxygen run, etc. Good luck!
I did some research on this... From the doxygen manual :
Important: The documentation of global functions, variables, typedefs,
and enums will only be included in the
output if the file they are in is
documented as well.
There you go !