I'm running doxygen 1.8.3.1 under SLED 10.4 (linux), and am trying to document a C header file which contains structs similar to the following:
/** Test struct definition */
typedef struct
{
int member_1; /**< Single-line detailed description */
int member_2; /**< Multi-line detailed description. Blah
blah blah */
} TEST_S;
Doxyfile is the default as generated by doxygen -g, with the only change being that I have edited the INPUT tag to point to my source.
Doxygen generates simple memdoc paragraphs from the single-line descriptions as expected, however, the multi-line descriptions are somehow being handled such the first line gets formatted as a code fragment. I have no idea why. The actual HTML that is generated is as follows:
<pre class="fragment"> Multi-line detailed description. Blah
</pre><p> blah blah </p>
Why isn't Doxygen generating just a simple paragraph?
This appears to be bug in Doxygen's support for Markdown in the 1.8.3.1 release (I wasn't able to reproduce the problem with Doxygen 1.8.2). If you disable markdown support in the configuration file:
MARKDOWN_SUPPORT = NO
The page is rendered correctly.
Alternatively if you switch your comment to a leading doxygen comment:
/** Multi-line detailed description. Blah
blah blah */
int member_2;
Or move the comment to the following line:
int member_2;
/**< Multi-line detailed description. Blah
blah blah */
it should be rendered correctly.
This issue has been reported to the Doxygen development group (https://bugzilla.gnome.org/show_bug.cgi?id=699437).
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.
If I write some URL in source code comments like:
/**
* Here is an inline link [test](http://www.test.com).
* More information:
* test
*/
I enabled GENERATE_XML in Doxygen. This is what it generates:
<para>Here is an inline link [test](<ulink url="http://www.test.com">http://www.test.com</ulink>).
More information:
<ulink url="http://www.test.com">test</ulink> </para>
After converting the tags, I can create a Markdown content like:
Here is an inline link [test](http://www.test.com).
More information:
test
Note that the Markdown link [test](http://www.test.com) is polluted, which will break the link after I feed this into another Markdown processor. I need this as I want to write some markdown in comments, and extract it to some structured data formats for other tools to processing the markdown. I have disabled MARKDOWN_SUPPORT in Doxygen.
I have tried disable AUTOLINK_SUPPORT in doxyfile, but it can only disable internal type link to class/method/...
Solution for the mentioned problem, auto linking a web address, is to use [test](%http://www.test.com). By means of the % sign the (automatic) linking is suppressed.
In the documentation, paragraph "Step 3: Documenting the sources":
Links are created for words corresponding to documented classes (unless the word is preceded by a %; then the word will not be linked and the % sign is removed).
Note: in the above quote the wording is only for classes but it does work on other places as well. The same "problem" occurs in other places:
Description of AUTOLINK_SUPPORT
FAQ Doxygen automatically generates a link to the class MyClass somewhere
in the running text. How do I prevent that at a certain place?
Paragraph Links to classes
Paragraph "\%"
Is there a way to customize the HTML output for an .ini configuration file with incorporated comments, as for example:
[MySection]
;This is an extensive description of MyParameter (possibly with #commands after semicolon?)
MyParameter=MyValue
Despite this is a special usage, I would like to have each parameter parsed/listed separately with description (and unit? and recommended value?). The file could also look like this:
[MySection]
;#brief A brief description
;#details A detailled description
;#unit cows (The physical unit of the parameter)
;#recommendedValue 5 cows
MyParameter=7
Currently, I'm including the .ini file with #include/#verbinclude - unfortunately, without syntax highlighting. Thanks.
OK, I'm assuming that you included the file using the FILE_PATTERNS tag, so that at least the file is listed in your documentation. Additionally you have to set EXTENSION_MAPPING tag to tell doxygen how to interpret this file. Unfortunately the INI file syntax is not supported by doxygen. At this point you have two possibilities:
Writing a custom input-filter (e.g. in perl) and add this as INPUT_FILTER
Varying the comments so that the doxygen parser gets a valid code corresponding to the programming language you have defined in EXTENSION_MAPPING.
For example if you have set EXTENSION_MAPPING = ini=C Then your inifile should look like this:
;/// #file myinifile.ini
;/// #brief A brief description.
;/// #details A detailled description.
;/// #unit cows (The physical unit of the parameter)
;/// #recommendedValue 5 cows
MyParameter=7
;
The additional slashes /// are needed to tell the doxygen parser that this line is a comment line which shall be processed by the doxygen.
Also note the last semicolon ; which is needed since the doxygen C parser is expecting a closing ; after each declaration.
I am working with some legacy code, for which I am generating XML documentation using doxygen. I have two problems with this kind of code. First it contains invalid comments. For example:
///#struct E
enum E
{
E1, E2, E3;
};
This causes doxygen to generate output for struct with name E, which is not in the code. My second problem is with HTML links. For example, for the following input:
///#brief For info about this struct see: <a href="http://www.foo.com/bar&bar"\>
struct S
{
int i;
}
the doxygen generated output is not a valid XML because the & in the link is not properly escaped.
For the above reasons I would like doxygen to ignore some comments. Is this possible?
I don't think that doxygen has a simple switch for this, however, you can write your own INPUT_FILTER program to clean up the file (by stripping out comments, for example) before doxygen runs.
I noticed and tested that html comments within a doxygen comment will be ignored:
///#brief some comment here <--! ignored here --> also continues over.
As far as the & not being escaped, have you noticed \& would escape it? Maybe this is a solution for that part.