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 /.
Related
Doxygen has a \file command, I had a look at different code bases and it seems some projects use it, some don't.
Having to maintain this adds some overhead (needs to be corrected when splitting files up) sometimes developers forget to do it.
Is there a way to infer this, eg: use the first doxygen formatted comment in the file as the \file comment.
Otherwise what is a good rule of thumb for when to use \file or not?
Note, I tried removing this command from all files and the output changed to group information less usefully and the order of some information changed, so it does make a difference.
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'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.
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.