I want to add a Windows path that contains backslashes to a doxygen comment like this:
/**
*
* Returns common AppData directory, usually C:\ProgramData\
*
*/
I tried it with two backslashes but CLion always displays it as new section. Is this a problem with CLion or am I doing it wrong?
Doxygen will see the \ProgramData as a possible command and leave it out. Solutions for this are either:
escaping the backslash so: C:\\ProgramData\\
using backticks, this will also change the font (something I would prefer to signal that it is a computer directory:
`C:\ProgramData\`
Related
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 would like to write a Doxygen comment that names the file in which the comment occurs. Rather than write the filename explicitly, I would like Doxygen to supply me with it. Thus, if I change the name of the file, or move some of the content into a different file, I don't need to change hard-coded instances of the name.
For a concrete example, let's say I'm adding comments to functions in array.hpp, and I want the comment for certain functions to say "This function should only be used within array.hpp." I want to be able to write
/**
* This function should only be used within #thisfile.
*/
where #thisfile is a Doxygen expression that translates into array.hpp within the file array.hpp.
I've looked at the Doxygen documentation, including "Automatic link generation/Links to files" and the entire "Special Commands" section, but I haven't found what I'm looking for. Does such functionality exist?
Note that essentially the same question was asked on the Doxygen mailing list a few weeks ago. It has not received any replies.
General
As far as I know such functionality does not exist out-of-the-box. But you can add it by configuring an INPUT_FILTER in your Doxyfile. The path to the file is passed as an argument to the filter by doxygen. This can be used by the filter to replace your keyword (for example #thisfile) with the path to the file.
Below I give an example how to implement this with bash. A solution for other shells or Windows should be quite similar.
Example for bash
Write a short bash script infiltrate_filename.sh:
#!/bin/bash
pathToScript=`pwd`"/"
sed -e "s:#thisfile:${1/$pathToScript/}:g" $1
This script truncates the path to the file by the working directory. The resulting string is used to replace the keyword of your choice (here: #thisfile).
Make your script executable: chmod +x infiltrate_filename.sh
Set the INPUT_FILTER in your Doxyfile to INPUT_FILTER = ./infiltrate_filename.sh
That's it! 🎉 Now you can use #thisfile in your documentation blocks and it will be replaced by the path to the file. As the paths are relative to Doxygen's working directory they will automatically be linked to the file.
Notes
This solution assumes that the filter script is located in the working directory of doxygen (for example ~/my_project) and that the INPUT files are in subdirectories of the working directory (for example ~/my_project/src/foo/bar).
I have tested this example on a minimum working example. I am not a bash or sed expert. This solution may be improvable.
I am creating a test list in Doxygen using the \test special command. I understand that I can click on the class name for that section and get taken through to the page that this test is in reference too.
What I would like however is in the test description for it to have a line which is the full file path.
Is there a special command to do this? or do I have to physically type it out into every comment block. below I have shown an example of what I want.
Class myTest
Perform a set of tests to verify foo & bar.
located in C:\MyFile
but I would like to write out my Doxygen comment like this:
/** \test
* Perform a set of tests to verify foo & bar.
* located in:
* \fullFilePath
*/
Is this possible?
Having scoured the special commands I've come to the conclusion that there is no Doxygen special command to give the result as in the question.
Doxygen does provide automatic hyperlinking for pages/files that it knows exist. Therefore in order to "solve" this problem[1] I have added the minimal amount of path name that is required in order to create a navigatable link. This solution looks like:
/** \test
* Perform a set of tests to verify foo & bar.
* located in:
* someFolder/myFile.cpp
*/
This would work for a file path like: C:/parentFolder/childFolder/someFolder/myFile.cpp
[1] The original question was focused around not having to type out the filepath into every comment block. This solution is a compromise between not having a special command and not having to write out the complete file path (which sometimes could be very long)
I have a framework which I am extending. There are some source folders which contain quite a lot of files and I want to document my work (especially those files which come from me) using doxygen.
Any file I am documenting contians a header:
/**
* #file my_file.c
* #author Stefan F.
* #date 28.05.2014
*
* #brief This file is awesome!
*/
Can I somehow tell doxygen to NOT include files without such a header?
I have already set
EXTRACT_ALL = NO
Files which don't have a doxygen header are not generated but they are still listed in the file list.
Does anyone know how to configure doxygen to get that behavior?
I'm not aware of any part of Doxygen that will do exactly what you are looking for, however, the simplest way to achieve your aim is simply to only list the files you want doxygenning in the doxyfile INPUT line.
INPUT = my_file_1.cpp myfile2.cpp moreofmyfiles/etc.cpp
(Beware it's a space separated list.)
Depending on your folder structure you may need to set RECURSIVE = NO
If it's your own personal project and you can name your file myname_file.cpp you could use FILE_PATTERNS to select only those files beginning "myname_* - but I'm expecting that's not a viable set of circumstances.
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 /.