I have some trouble understanding some Doxygen command taking options as first argument (using HTML output).
Here, it is about the \include command but I believe that the answers (if any) will apply to other commands.
The manual says:
You can add option {lineno} to enable line numbers for the included code if desired.
You can add option {doc} to treat the file as documentation rather than code.
I can't get this to work.
This:
\include doc path/to/my/file
works fine. But the file content is considered as code (which is perfectly normal), and it actually holds some generated content that I want to be formatted as documentation.
I tried these (yeah, don't laugh, please):
\include doc path/to/my/file
\include [doc] path/to/my/file
\include {doc} path/to/my/file
\include {[doc]} path/to/my/file
\include [{doc}] path/to/my/file
but none of these works.
And its the same behavior with the lineno option.
To be complete, I have to mention that the manual gives some info about the notation here:
Some commands have one or more arguments. Each argument has a certain range:
If braces are used the argument is a single word.
If (round) braces are used the argument extends until the end of the line on which the command was found.
If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.
But I don't understand how this relates to the above quote of the \include command manual.
Anybody has a clue ?
Doxygen version: 1.8.11 (Ubuntu 16.04 's latest).
First one has to distinguish between the different versions of doxygen. In the 1.8.11 version there are no options to e.g. the \include command, they are introduced in version 1.8.15.
The syntax for e.g. the \include command is in 1.8.15:
\include[{lineno,doc}]
in the newer version this is written as:
\include['{'option'}']
the rewrite was done because of it was not completely clear. Here (the new version, but this syntax is valid for 1.8.15 as well) the square brackets ([ and ]) signal the optionality the '{' and '}' signal that the curly brackets are mandatory. The option in this case can be either lineno or doc. furthermore you don't see a space between after \include and the curly bracket, this shouldn't be there, the curly brackets are part of the command. In case a space would be present it would be seen as the end of the command and the { would be start of the argument.
In case of \include with say filename xx.h we can have:
\include xx.h
\include{lineno} xx.h
\include{dox} xx.h
This is about the options the other quote is about the arguments of a command.
Related
We use DocFx in our projects. We would like to check for no problems in VSCode but we get the warning link.no-such-reference for DocFx Note formatting which uses square brackets.
Do you support suppression of problems like using:
[//]: # (<!-- markdownlint-disable line-length -->)
Could not find any documentation about suppressing one problem type once at a single code line.
I have a Base64 encoded string in a text file that is one line. In other words it contains no line breaks. I want to insert a line break every 78 characters.
None of the "wrap" extensions I have found do this, since they're geared for word wrapping and use word boundaries. Running any of these functions does nothing since the string contains no spaces or word boundaries.
I can do it on Unix using something like fold -w 78 but this seems like something that should exist in VS Code or at least an extension.
I'm not aware of an extension that does specifically what you're asking for, but what I would do is use the Edit with Shell Command extension, and use it to run fold -w 78 on the text in question from within VSCode. The extension even has a "quick command" feature you can use to save that command for quick use if it is something you do often.
I use that extension fairly often for one-off transformations with things like sort, sed, tr, and fmt. It's really handy when you know how to express the desired transformation as a shell command.
I am documenting my code with doxygen and want to introduce a separating line after a short description. What command can I use to include a separator? I have seen a series of separating lines in the doxygen manual but cannot find the appropriate command.
As noted in albert's comment, the syntax is <hr>.
Note that this does not work equally well in all output formats, but it does work in HTML. See albert's comment below.
I have a mainpage.dox file which is invoked in the configuration file as:
USE_MDFILE_AS_MAINPAGE = ../mainpage.dox
Inside the document I provide instructions on compiling. I would like to list the compiler option as -L/$(MKLROOT)/lib/intel64 -lmkl_rt, however the $(MKLROOT) part is expanded. Is there a way to prevent this from happening?
When I put the following in mainpage.md
1 Test with backticks `-L$(MKLROOT)/lib/intel64 -lmkl_rt`
2 Test without backticks -L\$(MKLROOT)/lib/intel64 -lmkl_rt
3 Test with code <code>-L\$(MKLROOT)/lib/intel64 -lmkl_rt</code>
#verbatim
4 Test with verbatim -L$(MKLROOT)/lib/intel64 -lmkl_rt
#endverbatim
The $(MKLROOT) in the first example gets (incorrectly) expanded.
The other three examples work as expected (using doxygen 1.8.5)
Note that USE_MDFILE_AS_MAINPAGE expects a pure markdown file, not something with a /*! .. */ comment block.
FWIW the latest version of Doxygen as of this writing (1.8.15) still behave in the same way and escaping the backslash still doesn't work. I'm using the following workaround for now:
`-L$``$(MKLROOT)`
which, while ugly, works and doesn't require adding the <code> tags everywhere.
I've also created an issue in Doxygen asking for this to be changed.
I've just installed and setup an instance of Doxygen, but out of the box it only finds TODO tags in code when marked in a block like:
/**
* #todo Foo
*/
It doesn't seem to find:
// TODO Foo
// FIXME Bar
// #todo Baz
Most IDE's and bug trackers which handle parsing are fine with them, is there an easy way to configure Doxygen to find them and list them as ToDo items?
There are a number of examples and methods we can use:
For a one line comment with valid doxygen commands (e.g. \todo) you would use
/// \todo Some (optional) text
Note the three forward slashes, not the usual two. See point three on the second list in the special documentation blocks section of the doxygen documentation. This can be used to add new todo items to your source code.
Generally one can define custom tags (like FIXME) by defining an alias in the Doxygen configuration file. For example
ALIASES += FIXME="\todo"
which will allow you to write \FIXME in your source code and the comments prefixed with \FIXME will be included in you todo list in the final documentation. The problem here is that you have to prefix your aliases with the \ (or #) symbol and begin the comment with three leading forward slashes which, if you want to leave the FIXMEs in your code as they are, is not an option.
Finally, an alternative method, and what I think you are looking for, would be to preprocess your source files using the INPUT_FILTER configuration file option. This option defines a command that is applied to each of your source files before doxygen builds the documentation, so we can define a command which replaces instances of TODO and FIXME with valid doxygen markup.
INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"
This filter replaces all instances of // FIXME (with any amount (or none) of whitespace between // and FIXME) with /// \todo. This substitution is made internally by doxygen only: your source files are not modified on disk.
Note: This last point was inspired by the accepted answer to the question Getting doxygen and MSVC TODO tags to work together. However, that answer used the FILE_VERSION_FILTER configuration option rather than INPUT_FILTER. I think that the latter (INPUT_FILTER) is actually more appropriate here. Also, the sed command used in that answer does not work for me.