summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorDimitri van Heesch <dimitri@stack.nl>2018-08-19 14:10:55 (GMT)
committerDimitri van Heesch <dimitri@stack.nl>2018-08-19 14:10:55 (GMT)
commit0b4b3698b29436b299d4e4a315d610bc1ab98acb (patch)
tree1babc69fbeab1211926ed7462a9db6ec50809d89 /doc
parent9ba8bd85999fa7423eb5b44c680e72ad2e9c31bf (diff)
downloadDoxygen-0b4b3698b29436b299d4e4a315d610bc1ab98acb.zip
Doxygen-0b4b3698b29436b299d4e4a315d610bc1ab98acb.tar.gz
Doxygen-0b4b3698b29436b299d4e4a315d610bc1ab98acb.tar.bz2
Bug 691689 - Line numbers for examples
Diffstat (limited to 'doc')
-rw-r--r--doc/commands.doc77
1 files changed, 41 insertions, 36 deletions
diff --git a/doc/commands.doc b/doc/commands.doc
index 6c680ee..2e51d79 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -442,14 +442,15 @@ Structural indicators
\endlatexonly
</p><hr>
-\section cmdexample \\example <file-name>
+\section cmdexample \\example[{lineno}] <file-name>
\addindex \\example
Indicates that a comment block contains documentation for a source code
- example. The name of the source file is \<file-name\>. The text of
- this file will be included in the documentation, just after the
- documentation contained in the comment block. All examples are placed
- in a list. The source code is scanned for documented members and classes.
+ example. The name of the source file is \<file-name\>.
+ The contents of this file will be included in the documentation, just after the
+ documentation contained in the comment block.
+ You can add option `{lineno}` to enable line numbers for the example if desired.
+ All examples are placed in a list. The source code is scanned for documented members and classes.
If any are found, the names are cross-referenced with the documentation.
Source files or directories can be specified using the
\ref cfg_example_path "EXAMPLE_PATH"
@@ -2151,16 +2152,12 @@ Commands for displaying examples
for the corresponding \mbox{\LaTeX} documentation that is generated by doxygen.
\endlatexonly
- Alternatively, the \ref cmdsnippet "\\snippet" command can be used to
- include only a fragment of a source file. For this to work the
- fragment has to be marked.
-
\sa sections \ref cmdline "\\line", \ref cmdskip "\\skip",
\ref cmdskipline "\\skipline", \ref cmduntil "\\until", and
\ref cmdinclude "\\include".
</p><hr>
-\section cmdinclude \\include <file-name>
+\section cmdinclude[{lineno|doc}] \\include <file-name>
\addindex \\include
This command can be used to include a source file as a block of code.
@@ -2194,8 +2191,20 @@ 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.
+
+ \note Some that when using the `{doc}` option,
+ commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
+ this command due to the moment of parsing.
+
+ \note The included documentation should not have comment signs in it as they will appear
+ in the documentation as well.
+
\sa sections \ref cmdexample "\\example", \ref cmddontinclude "\\dontinclude",
- \ref cmdverbatim "\\verbatim" and \ref cmdincludedoc "\\includedoc".
+ \ref cmdverbatim "\\verbatim", \ref cmdincludedoc "\\includedoc", and
+ \ref cmdsnippet "\\snippet".
<hr>
\section cmdincludelineno \\includelineno <file-name>
@@ -2204,21 +2213,14 @@ Commands for displaying examples
This command works the same way as \ref cmdinclude "\\include", but will add line
numbers to the included file.
- \sa sections \ref cmdinclude "\\include" and \ref cmdsnippetlineno "\\snippetlineno".
+ \sa sections \ref cmdinclude "\\include{lineno}".
<hr>
\section cmdincludedoc \\includedoc <file-name>
\addindex \\includedoc
- This command works the same way as \ref cmdinclude "\\include", but it will include
- the content of the file as if it were at the place where this command is called.
- The result is that the content is parsed by doxygen and placed in the documentation.
-
- \note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
- this command due to the moment of parsing.
-
- \note The included documentation should not have comment signs in it as they will appear
- in the documentation as well.
+ This command is obsolete and is still supported for backward compatibility reasons,
+ it works the same way as \ref cmdinclude "\\include{doc}"
\sa section \ref cmdinclude "\\include".
@@ -2278,7 +2280,7 @@ Commands for displaying examples
See section \ref cmddontinclude "\\dontinclude" for an example.
<hr>
-\section cmdsnippet \\snippet <file-name> ( block_id )
+\section cmdsnippet \\snippet[{lineno|doc}] <file-name> ( block_id )
\addindex \\snippet
Where the \ref cmdinclude "\\include" command can be used to include
@@ -2321,34 +2323,37 @@ 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.
+
+ \note Some that when using the `{doc}` option,
+ commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
+ this command due to the moment of parsing.
+
+ \note The included documentation should not have comment signs in it as they will appear
+ in the documentation as well.
+
see section \ref cmddontinclude "\\dontinclude" for an alternative way
to include fragments of a source file that does not require markers.
- \sa section \ref cmdsnippetdoc "\\snippetdoc" and \ref cmdsnippetlineno "\\snippetlineno".
<hr>
\section cmdsnippetlineno \\snippetlineno <file-name> ( block_id )
\addindex \\snippetlineno
- This command works the same way as \ref cmdsnippet "\\snippet", but will add line
- numbers to the included snippet.
+ This command is obsolete and is still supported for backward compatibility reasons,
+ it works the same way as \ref cmdsnippet "\\snippet{lineno}"
- \sa sections \ref cmdsnippet "\\snippet" and \ref cmdincludelineno "\\includelineno".
+ \sa sections \ref cmdsnippet "\\snippet{lineno}"
<hr>
\section cmdsnippetdoc \\snippetdoc <file-name> ( block_id )
\addindex \\snippetdoc
- This command works the same way as \ref cmdsnippet "\\snippet", but it will include
- the content of the file between the `block-id`s as if it were at the place where this command is called.
- The result is that the content is parsed by doxygen and placed in the documentation.
-
- \note Some commands like \ref cmdcond "\\cond" and \ref cmdif "\\if" don't work with
- this command due to the moment of parsing.
-
- \note The included documentation should not have comment signs in it as they will appear
- in the documentation as well.
+ This command is obsolete and is still supported for backward compatibility reasons,
+ it works the same way as \ref cmdsnippet "\\snippet{doc}"
- \sa section \ref cmdsnippet "\\snippet" and \ref cmdincludedoc "\\includedoc".
+ \sa section \ref cmdsnippet "\\snippet{doc}" and \ref cmdinclude "\\include{doc}".
<hr>
\section cmduntil \\until ( pattern )