How to include multiple paragraphs in the Remarks section using Doxygen?

Question

I finally waive the angle tax imposed on me by the Microsoft XML documentation format (and what's the point, since the MSVC environment still doesn't do anything interesting for C ++ projects) and switches my current project to using Doxygen with syntax Javadoc style.

It is fantastic. The built-in documentation is much easier to read and print, and the generated output is much more useful and versatile. In particular, I have the MULTILINE_CPP_IS_BRIEF parameter MULTILINE_CPP_IS_BRIEF , which allows me to write the “short” description as long as I want, and then break my “detailed” documentation into paragraphs using blank lines. In other words:

 /// Changes the active viewing area of the currently selected region. /// /// The modification is merely enqueued. This function has no effect until the /// FlushRegion() function is called. /// /// Newly-exposed regions will not be repainted automatically. The user must also /// call the UpdateRegion() function on these regions to cause their contents to /// be redrawn. /// /// @param dx The amount, in pixels, to shift the visible region horizontally. /// @param dy The amount, in pixels, to shift the visible region vertically. /// /// @remarks /// Note that this function is reentrant, but not thread-safe! void ScrollRegion(int dx, int dy); 

This gives me exactly the result that I want, while preserving the number of noisy meta-commands, such as @brief and \details , that I should use.

The problem occurs when I try to include the second paragraph in the Remarks section, just like I (implicitly) for the Details section. For example:

 /// Changes the active viewing area of the currently selected region. /// /// The modification is merely enqueued. This function has no effect until the /// FlushRegion() function is called. /// /// Newly-exposed regions will not be repainted automatically. The user must also /// call the UpdateRegion() function on these regions to cause their contents to /// be redrawn. /// /// @param dx The amount, in pixels, to shift the visible region horizontally. /// @param dy The amount, in pixels, to shift the visible region vertically. /// /// @remarks /// Note that this function is reentrant, but not thread-safe! /// /// If thread safety is required, the user must handle locking and unlocking /// the region manually. void ScrollRegion(int dx, int dy); 

The generated output does not interpret the second paragraph in the @remarks section as part of the comments. I can say because it does not have padding at the same level in the HTML output file, and this is not under the <simplesect kind="remark"> in the XML output.

I tried to add a @par command at the beginning of the second paragraph, but that did not do what I wanted. The new paragraph is still not a child of the Remarks section. In the XML output, it is placed inside the new <simplesect kind="para"> , which is native to the original <simplesect kind="remark"> .

During the research, I saw that someone else duplicated the @remarks command:

 /// Changes the active viewing area of the currently selected region. /// /// The modification is merely enqueued. This function has no effect until the /// FlushRegion() function is called. /// /// Newly-exposed regions will not be repainted automatically. The user must also /// call the UpdateRegion() function on these regions to cause their contents to /// be redrawn. /// /// @param dx The amount, in pixels, to shift the visible region horizontally. /// @param dy The amount, in pixels, to shift the visible region vertically. /// /// @remarks /// Note that this function is reentrant, but not thread-safe! /// @remarks /// If thread safety is required, the user must handle locking and unlocking /// the region manually. void ScrollRegion(int dx, int dy); 

This gives the result that I desire. Both paragraphs are embedded in the <para> tags under the <simplesect kind="remark"> in the XML output file, and the visual relationships are correct in the HTML output. But this is ugly and looks like a mistake to me.

Is there a standard way to do this that I am missing? Of course, I'm not the first person who wants a few paragraphs in the "notes" section of my documentation ... And this is not limited to @remarks ; the same thing happens with @internal , for example.

I have the latest version of Doxygen (1.8.2) installed, but I very much doubt that it depends on the version.

Answer 1

Your last sample code, i.e.

 /// @remarks /// Note that this function is reentrant, but not thread-safe! /// @remarks /// If thread safety is required, the user must handle locking and unlocking /// the region manually. 

is exactly the expected use of \remarks for comment blocks with multiple paragraphs. From the doxygen manual (my attention):

\remark { remark text }

Launches a paragraph into which one or more comments can be entered. This paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands can be used inside a paragraph. Several adjacent \remark will be merged into one paragraph. Each note begins with a new line. Alternatively, one \remark may mention several comments. The \remark ends when an empty string or some other sectioning command is encountered.

So, \remark (and \remarks , which is the same as \remark ), ends at the end of the paragraph, but the adjacent \remark will be sewn together to form a single \remark block.

You have the right to say that this behavior is not limited to \remarks and \remark . The same applies to any command that takes a paragraph of text as an argument, see, for example, \bug , \todo , \warning , etc.

Answer 2

One solution that seems to work, which I did not mention here, is to end your lines with \ n. This will cause everything to be grouped together, placing in an empty space that you might want to see.

If you need an empty line, make sure that the line above is \ n, and you have an empty line with \ n on it.

In your example, you need:

 /// @remarks /// Note that this function is reentrant, but not thread-safe!\n /// \n /// If thread safety is required, the user must handle locking and unlocking /// the region manually. 

And it should look the way you want it to appear.

Answer 3

If you don't like having multiple @remarks lines in your source for multi-paragraph comments, I think you can use @parblock and @endparblock to include multiple paragraphs for one @remark.

Answer 4

Solutions can be generalized (doxygen 1.8.9.1). I used:

 /// \par Title /// text of paragraph 1\n /// /// text of paragraph 2\n /// /// ~~~ /// Some code / sketch /// ~~~ 

kjkAe4Wbasj6 Three paragraphs are indented and the Title is printed in bold above them. Of course, \par Title can be replaced by \remark . A magic phrase is \n at the end of a paragraph, and blank lines can be optionally inserted. Blank lines do not require \n . Unfortunately, I did not find a way to add another indented paragraph following the code section.