Bug 691689 - Line numbers for examples

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 )