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've been passed an array of exits or just one.</para>
<para>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.</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>
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.
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?
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.
Related
I'm dealing with one issue on GitHub and for that, the moderator is requesting me to share the output of certain bash commands in the comments. I'm sharing the output of requested commands in the form of code blocks and I know how to insert code block in Markdown:
The output of the command
.
.
.
However, the problem with the above syntax is that if the command output has let say 500 lines then it will display all the 500 lines in the Markdown output. In fact, there total of 3 such long code blocks in my comment. Because of that, code blocks consume a significant amount of space in my comment and my comment seems too long.
So, is there any way that my code block would display only a limited number of lines with a scrolling feature specific to that block only e.g. it should display only 10 lines, and for the rest of the lines, it should have vertical scrolling. Through this, my comment won't seem too long and the moderator would also be to focus on other non-command text (i.e. content other than code blocks) in my comment.
GitHub Flavored Markdown allows you to use html tags. So you can use details html block to hide your long code.
<details>
<summary>
summary
</summary>
details
</details>
It looks like this collapsed:
and expanded:
I'm having a hard time locating the documentation explaining how to add a line break in Doxygen markdown.
I've tried using two spaces at the end of the line, and I've also tried a single or double newline, but none of these are working for me.
I'm using Doxygen version 1.8.9.1.
Put a HTML-break tag <br> where you want to have a linebreak, does the job.
At least for man page output and HTML output.
Add \n followed by a space at the end of your line [1].
Especially recommended when editing with Emacs, which reacts in weird ways to the other suggested solution <br>.
[1] As per #albert's comment. Works for me under Doxygen 1.8.13.
Can't seem to find how to do the following:
I have a large documentation #page and I would like to split out the sections into separate files, eg.
page.dox
section1.dox
section2.dox
How do i do that? In essence, I am looking for a Latex \input{} equivalent.
You can simply repeat the page command, and make sure the page parts are listed in the right order.
For example:
page.dox:
/**
#page mypage Page title
Introduction text
*/
section1.dox:
/**
#page mypage
#section mysection1 First section
First section text
*/
section2.dox:
/**
#page mypage
#section mysection2 Second section
Second section text
*/
With the config file specifying:
INPUT = page.dox section1.dox section2.dox
Doxygen will then turn the parts into a single page.
I too am unable to find any means of bringing text from another file into the same page.
The \includeand related commands are specifically designed for including code, verbatim HTML, etc. and processing of any Doxygen commands within the included text is turned off. This is perfect for what it is intended for, but not really of use for your needs.
The simplest method to achieve what you want is probably to write a short script in your favourite scripting language, to concatenate the original source files into one larger source file for Doxygen to subsequently process.
Are you sure you want to do this? Is there a particular reason why you don't want to have the sections on separate pages? I find it difficult to see a case where the source is so long that it warrants being split up, but the resulting output page does not.
The coding guidelines of programming language limit the line length, e.g. to 80 characters. How can I add a URL that is longer than that limit to Doxygen comments? How do I tell Doxygen that multiple lines are to be joined to form the actual link?
Example:
##
# #file mycode.py
# #sa See the documentation: http://some.host.some.domain/and_here
# _we_have_a_very_long_URL_that_can_not_be_written_in_one_line
# _because_it_would_exceed_the_line_length_limit
The example above doesn't work, and it doesn't work either to end the lines with a backslash (the backslash is just copied to the documentation).
You can try it this way. It worked for me. However I'm not a 100% sure its going to work for you. Our IDE use whitespaces as indentation and not tabs. So when you break the line, hence the link, it might not work.
<a href="http://stackoverflow.com/questions/9098680/
doxygen-link-to-a-url-doesnt-generate-the-link-correctly">
link
</a>
You could use an alias to abbreviate the long URL, i.e.
##
# #file mycode.py
# #sa See the documentation: #longurl
and in the Doxyfile define
ALIASES = longurl="http://some.host.some.domain/and_here/..."
This is performing necromancy an old question. I am answering for C++ style comments. But, if you make you link in the form:
/**
* [link_text](http://foo.com/bar/baz/qux/wibble/flob?id=deadbeef123456789abcdefghijklmnopqrstuvwxyz)
*/
You can wrap that URL in the following ways and the generated HTML output will still contain a working anchor tag:
/**
* [link_
text]
(http://foo.com/bar/baz/qux/wibble/
flob?id=deadbeef123456789abcdefghijklmnopqrstuvwxyz)
*/
Obviously this might make the comment block less readable. But this gives you an idea of what is possible. The main things that are advantagious here are being able to put the URL on a separate line from the link text, and then being able to wrap it at least once after a /.
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.