How should I use Doxygen commands with an option as first argument?

Question

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).

albert albert · Accepted Answer · 2019-06-13T16:05:01

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.

How should I use Doxygen commands with an option as first argument?

1 Answers