diff options
Diffstat (limited to 'doc/commands.doc')
-rw-r--r-- | doc/commands.doc | 83 |
1 files changed, 44 insertions, 39 deletions
diff --git a/doc/commands.doc b/doc/commands.doc index 6c680ee..a630aac 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 \\include[{lineno|doc}] <file-name> \addindex \\include This command can be used to include a source file as a block of code. @@ -2194,33 +2191,38 @@ 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> \addindex \\includelineno - This command works the same way as \ref cmdinclude "\\include", but will add line - numbers to the included file. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdinclude "\\include{lineno}" - \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. + This command is obsolete and is still supported for backward compatibility reasons, + it works the same way as \ref cmdinclude "\\include{doc}" - \note The included documentation should not have comment signs in it as they will appear - in the documentation as well. - - \sa section \ref cmdinclude "\\include". + \sa section \ref cmdinclude "\\include{doc}". <hr> \section cmdline \\line ( pattern ) @@ -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 ) |