From 9ecbe35ae2826b2404f37cc7e5d4377e39430b51 Mon Sep 17 00:00:00 2001 From: albert-github Date: Wed, 17 Apr 2019 14:28:49 +0200 Subject: Option syntax for commands is unclear Making documentation regarding option clearer and more consistent. --- doc/commands.doc | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/doc/commands.doc b/doc/commands.doc index ae27a7a..1ca9b38 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -29,9 +29,14 @@ Each argument has a certain range:
  • 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. + Paragraphs are delimited by a blank line or by a section indicator. Note that + {curly} braces are also used for command options, here the braces are mandatory + and just 'normal' characters. The strating curly brace has to directly follow + the command, so without whitspace. -If in addition to the above argument specifiers [square] brackets are used the argument is optional. +If in addition to the above argument specifiers [square] brackets are used the argument +is optional, unless they are placed between quotes in that case they are a mandatory +part of the command argument. Here is an alphabetically sorted list of all commands with references to their documentation: @@ -516,7 +521,7 @@ Structural indicators \endlatexonly
    -\section cmdexample \\example[{lineno}] +\section cmdexample \\example['{lineno}'] \addindex \\example Indicates that a comment block contains documentation for a source code @@ -1607,7 +1612,7 @@ ALIASES = "english=\if english" \ \endlatexonly
    -\section cmdparam \\param [(dir)] { parameter description } +\section cmdparam \\param '['dir']' { parameter description } \addindex \\param Starts a parameter description for a function parameter with name @@ -1616,7 +1621,7 @@ ALIASES = "english=\if english" \ the documentation of this (or any other) parameter is missing or not present in the function declaration or definition. - The \c \\param command has an optional attribute, (dir), specifying the direction + The \c \\param command has an optional attribute, `dir`, specifying the direction of the parameter. Possible values are "[in]", "[in,out]", and "[out]", note the [square] brackets in this description. When a parameter is both input and output, [in,out] is used as attribute. @@ -2186,7 +2191,7 @@ Commands for displaying examples \htmlonly

    \endhtmlonly

    -\section cmddontinclude \\dontinclude[{lineno}] +\section cmddontinclude \\dontinclude['{lineno}'] \addindex \\dontinclude This command can be used to parse a source file without actually @@ -2227,7 +2232,7 @@ Commands for displaying examples \ref cmdinclude "\\include".
    -\section cmdinclude \\include[{lineno|doc}] +\section cmdinclude \\include['{'option'}'] \addindex \\include This command can be used to include a source file as a block of code. @@ -2261,9 +2266,9 @@ Commands for displaying examples \note Doxygen's special commands do not work inside blocks of code. It is allowed to nest C-style comments inside a code block though. - 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. + The `option` can either be `lineno` or `doc`. + The `option` `lineno` can be used to enable line numbers for the included code if desired. + The `option` `doc` can be used to treat the file as documentation rather than code. \note Some that when using the `{doc}` option, commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with @@ -2350,7 +2355,7 @@ Commands for displaying examples See section \ref cmddontinclude "\\dontinclude" for an example.
    -\section cmdsnippet \\snippet[{lineno|doc}] ( block_id ) +\section cmdsnippet \\snippet['{'option'}'] ( block_id ) \addindex \\snippet Where the \ref cmdinclude "\\include" command can be used to include @@ -2393,9 +2398,9 @@ Commands for displaying examples Note also that the [block_id] markers should appear exactly twice in the source file. - You can add option `{lineno}` to enable line numbers for the snippet if desired. - - You can add option `{doc}` to treat the file as documentation rather than code. + The `option` can either be `lineno` or `doc`. + The `option` `lineno` can be used to enable line numbers for the included code if desired. + The `option` `doc` can be used to treat the file as documentation rather than code. \note Some that when using the `{doc}` option, commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with @@ -2574,7 +2579,7 @@ Commands for visual enhancements To have multiple words in typewriter font use \multiple words\.
    -\section cmdcode \\code [ '{''}'] +\section cmdcode \\code['{''}'] \addindex \\code Starts a block of code. A code block is treated differently @@ -3152,7 +3157,7 @@ class Receiver \ref cmdhtmlinclude "\\htmlinclude".
    -\section cmdimage \\image['{'[option]'}'] ["caption"] [=] +\section cmdimage \\image['{'option'}'] ["caption"] [=] \addindex \\image Inserts an image into the documentation. This command is format -- cgit v0.12 From bd645c0e3ee05582adf30dcd91af5eafec7733c4 Mon Sep 17 00:00:00 2001 From: albert-github Date: Sat, 20 Apr 2019 15:32:46 +0200 Subject: Option syntax for commands is unclear Corrected typo --- doc/commands.doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/commands.doc b/doc/commands.doc index 1ca9b38..8e91b9c 100644 --- a/doc/commands.doc +++ b/doc/commands.doc @@ -31,7 +31,7 @@ Each argument has a certain range:
  • If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator. Note that {curly} braces are also used for command options, here the braces are mandatory - and just 'normal' characters. The strating curly brace has to directly follow + and just 'normal' characters. The starting curly brace has to directly follow the command, so without whitspace. If in addition to the above argument specifiers [square] brackets are used the argument -- cgit v0.12