doxygen @par command breaking html output with missing <b> or errant </b> tags

Question

Doxygen noob here. I've searched and tried to resolve this for several hours now with no luck. The answer is likely to be something obvious I'm not familiar enough to see.

EDIT: Doxygen's @par command breaks the HTML output page (running doxy 1.8.0 via gui wizard), by either failing to insert an <b> inside the <dt>, or by inserting an errant </b> inside the </dt>, while similar commands (like @return and @note, for example) do not. Example comment (comment is on a function, if this matters...):

/** 
Register a new exit to the room object. Adds the exit to our exit_hash map with some safety checks for whether we've been passed an array of exits or just one.

New practice; there's now an exit hash map ([direction:hash])
and we add exits into our hash map as they're created. This is how guards
are now identified: they're assigned the hashes they guard as IDs.

@code
PLEASE WORK
@endcode

@return hrm

\note
This note consists of two paragraphs.
This is the first paragraph.

\par User defined paragraph:
Contents of the paragraph.

\par
New paragraph under the same heading.

\par
And this is the second paragraph.

More normal text.


*/

You may recognize part of the comment, as I've lifted it from the doxygen demonstration of the command's usage. This produces HTML output that ceases at "This is the first paragraph." under the \note command (all sections before this render properly), and the top of the doxygen page cites the error:

This page contains the following errors: error on line 422 at column 42: Opening and ending tag mismatch: dt line 0 and b Below is a rendering of the page up to the first error.

The XML renders (or appears to me, at least) properly and is as follows:

<detaileddescription>
    <para>Adds the exit to our exit_hash map with some safety checks for whether we&apos;ve been passed an array of exits or just one.</para>
    <para>New practice; there&apos;s now an exit hash map ([direction:hash]) and we add exits into our hash map as they&apos;re created. This is how guards are now identified: they&apos;re assigned the hashes they guard as IDs.</para>
    <para><programlisting><codeline><highlight class="normal">OH<sp/>JESUS<sp/>GOD<sp/>PLEASE<sp/>WORK</highlight></codeline></programlisting></para>
    <para>
        <simplesect kind="return"><para>hrm</para></simplesect>
        <simplesect kind="note"><para>This note consists of two paragraphs. This is the first paragraph.</para></simplesect>
        <simplesect kind="par"><title>User defined paragraph:</title><para>Contents of the paragraph.</para></simplesect>
        <simplesect kind="par"><title></title><para>New paragraph under the same heading.</para></simplesect>
        <simplesect kind="par"><title></title><para>And this is the second paragraph.</para></simplesect>
More normal text. 
    </para>
</detaileddescription>

HTML output at the error site:

<p>Register a new exit to the room object. </p>
<p>Adds the exit to our exit_hash map with some safety checks for whether we've been passed an array of exits or just one.</p>
<p>New practice; there's now an exit hash map ([direction:hash]) and we add exits into our hash map as they're created. This is how guards are now identified: they're assigned the hashes they guard as IDs.</p>
<div class="fragment"><pre class="fragment">OH JESUS GOD PLEASE WORK
</pre></div><dl class="section return"><dt>Returns:</dt><dd>hrm</dd></dl>
<dl class="section note"><dt>Note:</dt><dd>This note consists of two paragraphs. This is the first paragraph.</dd></dl>
<dl class="section user"><dt></b></dt><dd>And this is the second paragraph.</dd></dl>
<dl class="section user"><dt>User defined paragraph:</b></dt><dd>Contents of the paragraph.</dd></dl>
<dl class="section user"><dt></b></dt><dd>New paragraph under the same heading.</dd></dl>
<dl class="section user"><dt></b></dt><dd>And this is the second paragraph.</dd></dl>
<p>More normal text. </p>

Answer 1

I'm not sure but part of your problem may be that you are using a paragraph title on one of the paragraphs in your \note. From the doxygen manual page for \par:

If no paragraph title is given this command will start a new paragraph. This will also work inside other paragraph commands (like \param or \warning) without ending that command.

Which implies that adding a title will end any previous command block. Try re-ordering your documentation to match the \par documentation example and see if that produces the results you expect.

Also, what is on line 422?

Answer 2

I am in the same situation. Have .xhtml as my extension due to .svg dot diagrams. I have found that if you put an extra new line before and after @code blocks it seems to solve a lot of the problems:

/**
 * @par Example:
 * This is an example:
 * @code
 * // Some code
 * @endcode
 * The above example is AWESOME!
 */

The above creates XHTML errors but if I change it to:

/**
 * @par Example:
 * This is an example:
 *
 * @code
 * // Some code
 * @endcode
 *
 * The above example is AWESOME!
 */

Everything is fine again. This may or may not be a solution to your problem but has allowed me to keep my .xhtml extension whilst working around the doxygen XHTML output.

Answer 3

I've been toggling options/searching for errors in the comment format for days and it looks like I've finally isolated the issue, which I'll document here should someone else come looking:

I had set the HTML_FILE_EXTENSION option to .xhtml as recommended in the documentation for the DOT_IMAGE_FORMAT setting:

The DOT_IMAGE_FORMAT tag can be used to set the image format of the images generated by dot. Possible values are svg, png, jpg, or gif. If left blank png will be used. Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files visible in IE 9+ (other browsers do not have this requirement).

This setting isn't the cause of the error (bug report: https://bugzilla.gnome.org/show_bug.cgi?id=672472), but the setting was causing it to prevent the page from loading due to the unpaired tags. Returning this setting to .html doesn't resolve the issue of the extra </b> tag, but it does function as a workaround to keep it from breaking the page for now.