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.
Related
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 "\%"
I am trying to include a .ini file in the doxygen documentation of a C++ class, using \include. This works fine, but for some reason, doxygen treats the contents of the file as C code, which leads to strange formatting. I know \include surrounds the included file with a \code block, and that you can pass specific language information to the code block by using e.g. \code{.unparsed}. Is there a way to do the same with \include? \include{.unparsed} does not work...
Seems the answer to the question is "no": you cannot indicate a language when using \include, since doxygen tries to determine the language based on the extension. If it fails to do so, it reverts to C. If you do not want C formatting for unsupported file extensions, you can use \verbinclude instead of \include.
To distinguish this question from Doxygen: Adding a custom link under the "Related Pages" section which has an accepted answer that is not a real answer to the question, I specifically add prewritten to the question.
What I want:
Write one document tex file (without preamble, since this file will be \input-ed into a full document)
Import the document into Doxygen's HTML output.
Using Doxygen to produce tex file will probably not work, since it does too much layout work [This holds for its HTML output too like empty table rows 2015]. If Doxygen takes some other input that can easily be transformed into LaTeX, that will do.
You can easily add an already existing Latex file to your doxygen documentation using \latexonly\input{yourfile}\endlatexonly.
I would assume you put it e.g. under a doxygen \page.
I'm trying to document a C API which is all contained in a single C Header file. When I run doxygen, on the file, it's giving me errors for currently undocumented C Macros, but when I add the necessary documentation for macros, although the undocumented errors are cleared, the macros plus documentation do not appear in the doxygen generated html output.
Only a fraction of the documented header file, the structures, actually appears in any doxygen output. I can't see anything in configuration settings or documentation that would assist in clarifying why doxygen does not place documented code from the header file into its generated output.
Does anybody know why this would be the case?
See items 2 and 3 of the FAQ: http://www.doxygen.org/manual/faq.html
In short you are likely missing a comment block with #file to document your header file.
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 /.