diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index e9de927da0..7f5f65ae1b 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -3,6 +3,7 @@ * xref:install.adoc[Installation] * xref:usage.adoc[Getting Started] * xref:commands.adoc[Documenting the Code] +* xref:commands-list.adoc[Commands List] * xref:config-file.adoc[] * xref:generators.adoc[] * xref:design-notes.adoc[] diff --git a/docs/modules/ROOT/pages/commands-list.adoc b/docs/modules/ROOT/pages/commands-list.adoc new file mode 100644 index 0000000000..d86164a55c --- /dev/null +++ b/docs/modules/ROOT/pages/commands-list.adoc @@ -0,0 +1,176 @@ += Comprehensive List of Commands + +Below is the complete list of supported commands: + +* xref:commands/a.adoc[@a] +* xref:commands/addindex.adoc[@addindex] +* xref:commands/addtogroup.adoc[@addtogroup] +* xref:commands/anchor.adoc[@anchor] +* xref:commands/arg.adoc[@arg] +* xref:commands/attention.adoc[@attention] +* xref:commands/author.adoc[@author] +* xref:commands/authors.adoc[@authors] +* xref:commands/b.adoc[@b] +* xref:commands/brief.adoc[@brief] +* xref:commands/bug.adoc[@bug] +* xref:commands/c.adoc[@c] +* xref:commands/callergraph.adoc[@callergraph] +* xref:commands/callgraph.adoc[@callgraph] +* xref:commands/cite.adoc[@cite] +* xref:commands/class.adoc[@class] +* xref:commands/code.adoc[@code] +* xref:commands/concept.adoc[@concept] +* xref:commands/cond.adoc[@cond] +* xref:commands/copybrief.adoc[@copybrief] +* xref:commands/copydetails.adoc[@copydetails] +* xref:commands/copydoc.adoc[@copydoc] +* xref:commands/copyright.adoc[@copyright] +* xref:commands/date.adoc[@date] +* xref:commands/def.adoc[@def] +* xref:commands/defgroup.adoc[@defgroup] +* xref:commands/deprecated.adoc[@deprecated] +* xref:commands/details.adoc[@details] +* xref:commands/diafile.adoc[@diafile] +* xref:commands/dir.adoc[@dir] +* xref:commands/docbookinclude.adoc[@docbookinclude] +* xref:commands/docbookonly.adoc[@docbookonly] +* xref:commands/dontinclude.adoc[@dontinclude] +* xref:commands/dot.adoc[@dot] +* xref:commands/dotfile.adoc[@dotfile] +* xref:commands/e.adoc[@e] +* xref:commands/else.adoc[@else] +* xref:commands/elseif.adoc[@elseif] +* xref:commands/em.adoc[@em] +* xref:commands/emoji.adoc[@emoji] +* xref:commands/endcode.adoc[@endcode] +* xref:commands/endcond.adoc[@endcond] +* xref:commands/enddocbookonly.adoc[@enddocbookonly] +* xref:commands/enddot.adoc[@enddot] +* xref:commands/endhtmlonly.adoc[@endhtmlonly] +* xref:commands/endif.adoc[@endif] +* xref:commands/endinternal.adoc[@endinternal] +* xref:commands/endlatexonly.adoc[@endlatexonly] +* xref:commands/endmanonly.adoc[@endmanonly] +* xref:commands/endmsc.adoc[@endmsc] +* xref:commands/endparblock.adoc[@endparblock] +* xref:commands/endrtfonly.adoc[@endrtfonly] +* xref:commands/endsecreflist.adoc[@endsecreflist] +* xref:commands/enduml.adoc[@enduml] +* xref:commands/endverbatim.adoc[@endverbatim] +* xref:commands/endxmlonly.adoc[@endxmlonly] +* xref:commands/enum.adoc[@enum] +* xref:commands/example.adoc[@example] +* xref:commands/exception.adoc[@exception] +* xref:commands/extends.adoc[@extends] +* xref:commands/fdollar.adoc[@f$] +* xref:commands/file.adoc[@file] +* xref:commands/flbrace.adoc[@f{] +* xref:commands/flparen.adoc[@f(] +* xref:commands/flsquare.adoc[@f[] +* xref:commands/fn.adoc[@fn] +* xref:commands/frbrace.adoc[@f}] +* xref:commands/frparen.adoc[@f)] +* xref:commands/frsquare.adoc[@f]] +* xref:commands/headerfile.adoc[@headerfile] +* xref:commands/hidecallergraph.adoc[@hidecallergraph] +* xref:commands/hidecallgraph.adoc[@hidecallgraph] +* xref:commands/hideinitializer.adoc[@hideinitializer] +* xref:commands/hiderefby.adoc[@hiderefby] +* xref:commands/hiderefs.adoc[@hiderefs] +* xref:commands/htmlinclude.adoc[@htmlinclude] +* xref:commands/htmlonly.adoc[@htmlonly] +* xref:commands/if.adoc[@if] +* xref:commands/ifnot.adoc[@ifnot] +* xref:commands/image.adoc[@image] +* xref:commands/implements.adoc[@implements] +* xref:commands/include.adoc[@include] +* xref:commands/ingroup.adoc[@ingroup] +* xref:commands/interface.adoc[@interface] +* xref:commands/internal.adoc[@internal] +* xref:commands/invariant.adoc[@invariant] +* xref:commands/latexinclude.adoc[@latexinclude] +* xref:commands/latexonly.adoc[@latexonly] +* xref:commands/li.adoc[@li] +* xref:commands/line.adoc[@line] +* xref:commands/link.adoc[@link] +* xref:commands/mainpage.adoc[@mainpage] +* xref:commands/maninclude.adoc[@maninclude] +* xref:commands/manonly.adoc[@manonly] +* xref:commands/memberof.adoc[@memberof] +* xref:commands/msc.adoc[@msc] +* xref:commands/mscfile.adoc[@mscfile] +* xref:commands/n.adoc[@n] +* xref:commands/n.adoc[@n] +* xref:commands/name.adoc[@name] +* xref:commands/namespace.adoc[@namespace] +* xref:commands/noop.adoc[@noop] +* xref:commands/nosubgrouping.adoc[@nosubgrouping] +* xref:commands/note.adoc[@note] +* xref:commands/overload.adoc[@overload] +* xref:commands/p.adoc[@p] +* xref:commands/page.adoc[@page] +* xref:commands/par.adoc[@par] +* xref:commands/paragraph.adoc[@paragraph] +* xref:commands/param.adoc[@param] +* xref:commands/parblock.adoc[@parblock] +* xref:commands/post.adoc[@post] +* xref:commands/pre.adoc[@pre] +* xref:commands/private.adoc[@private] +* xref:commands/privatesection.adoc[@privatesection] +* xref:commands/property.adoc[@property] +* xref:commands/protected.adoc[@protected] +* xref:commands/protectedsection.adoc[@protectedsection] +* xref:commands/protocol.adoc[@protocol] +* xref:commands/public.adoc[@public] +* xref:commands/publicsection.adoc[@publicsection] +* xref:commands/ref.adoc[@ref] +* xref:commands/ref.adoc[@ref] +* xref:commands/refitem.adoc[@refitem] +* xref:commands/related.adoc[@related] +* xref:commands/relatedalso.adoc[@relatedalso] +* xref:commands/relates.adoc[@relates] +* xref:commands/relatesalso.adoc[@relatesalso] +* xref:commands/remark.adoc[@remark] +* xref:commands/remarks.adoc[@remarks] +* xref:commands/result.adoc[@result] +* xref:commands/return.adoc[@return] +* xref:commands/returns.adoc[@returns] +* xref:commands/retval.adoc[@retval] +* xref:commands/rtfinclude.adoc[@rtfinclude] +* xref:commands/rtfonly.adoc[@rtfonly] +* xref:commands/sa.adoc[@sa] +* xref:commands/secreflist.adoc[@secreflist] +* xref:commands/section.adoc[@section] +* xref:commands/see.adoc[@see] +* xref:commands/short.adoc[@short] +* xref:commands/showinitializer.adoc[@showinitializer] +* xref:commands/showrefby.adoc[@showrefby] +* xref:commands/showrefs.adoc[@showrefs] +* xref:commands/since.adoc[@since] +* xref:commands/skip.adoc[@skip] +* xref:commands/skipline.adoc[@skipline] +* xref:commands/snippet.adoc[@snippet] +* xref:commands/startuml.adoc[@startuml] +* xref:commands/static.adoc[@static] +* xref:commands/struct.adoc[@struct] +* xref:commands/subpage.adoc[@subpage] +* xref:commands/subsection.adoc[@subsection] +* xref:commands/subsubsection.adoc[@subsubsection] +* xref:commands/tableofcontents.adoc[@tableofcontents] +* xref:commands/test.adoc[@test] +* xref:commands/throw.adoc[@throw] +* xref:commands/throws.adoc[@throws] +* xref:commands/todo.adoc[@todo] +* xref:commands/tparam.adoc[@tparam] +* xref:commands/typedef.adoc[@typedef] +* xref:commands/union.adoc[@union] +* xref:commands/until.adoc[@until] +* xref:commands/var.adoc[@var] +* xref:commands/verbatim.adoc[@verbatim] +* xref:commands/verbinclude.adoc[@verbinclude] +* xref:commands/version.adoc[@version] +* xref:commands/warning.adoc[@warning] +* xref:commands/weakgroup.adoc[@weakgroup] +* xref:commands/xmlinclude.adoc[@xmlinclude] +* xref:commands/xmlonly.adoc[@xmlonly] +* xref:commands/xrefitem.adoc[@xrefitem] diff --git a/docs/modules/ROOT/pages/commands.adoc b/docs/modules/ROOT/pages/commands.adoc index 2f865b4848..364e46005d 100644 --- a/docs/modules/ROOT/pages/commands.adoc +++ b/docs/modules/ROOT/pages/commands.adoc @@ -56,6 +56,11 @@ The following commands can be used to format the text in the doc comments: | |=== +== Full List of Commands + +If you want to see the complete list of available commands and their details, +please check xref:commands-list.adoc[the Comprehensive Commands List]. + // == Documentation at other places // @class, @struct, @union, @enum, @fn, @var, @def, @typedef, @file, @namespace... diff --git a/docs/modules/ROOT/pages/commands/a.adoc b/docs/modules/ROOT/pages/commands/a.adoc new file mode 100644 index 0000000000..2f2279dd96 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/a.adoc @@ -0,0 +1,20 @@ += a + +== Syntax +@a <word> + +== Description +Displays the argument in italics. Use this command to emphasize words. Use this command to refer to member arguments in the running text. + +Equivalent to xref:commands/e.adoc[@e] and xref:commands/em.adoc[@em]. To emphasize multiple words use multiple words. + +== Example +``` + ... the @a x and @a y coordinates are used to ... + +``` +// [CODE_END] + + +== Rendering +\... the _x_ and _y_ coordinates are used to ... \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/addindex.adoc b/docs/modules/ROOT/pages/commands/addindex.adoc new file mode 100644 index 0000000000..6a19dfd247 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/addindex.adoc @@ -0,0 +1,7 @@ += addindex + +== Syntax +@addindex (text) + +== Description +This command adds (text) to the LaTeX , DocBook and RTF index. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/addtogroup.adoc b/docs/modules/ROOT/pages/commands/addtogroup.adoc new file mode 100644 index 0000000000..0d3c432c8b --- /dev/null +++ b/docs/modules/ROOT/pages/commands/addtogroup.adoc @@ -0,0 +1,35 @@ += addtogroup + +== Syntax +@addtogroup <name> [(title)] + +== Description +Defines a group just like xref:commands/defgroup.adoc[@defgroup], but in contrast to that command using the same more than once will not result in a warning, but rather one group with a merged documentation and the first title found in any of the commands. + +The title is optional, so this command can also be used to add a number of entities to an existing group using `@{` and `@}` like this: + +``` + /*! @addtogroup mygrp + * Additional documentation for group 'mygrp' + * @{ + */ + + /*! + * A function + */ + void func1() + { + } + + /*! Another function */ + void func2() + { + } + + /*! @} */ + +``` +// [CODE_END] + +== See Also +sections xref:commands/defgroup.adoc[@defgroup], xref:commands/ingroup.adoc[@ingroup], and xref:commands/weakgroup.adoc[@weakgroup]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/anchor.adoc b/docs/modules/ROOT/pages/commands/anchor.adoc new file mode 100644 index 0000000000..809a916e87 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/anchor.adoc @@ -0,0 +1,10 @@ += anchor + +== Syntax +@anchor <word> + +== Description +This command places an invisible, named anchor into the documentation to which you can refer with the xref:commands/ref.adoc[@ref] command. + +== See Also +section xref:commands/ref.adoc[@ref]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/arg.adoc b/docs/modules/ROOT/pages/commands/arg.adoc new file mode 100644 index 0000000000..4ca48947d3 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/arg.adoc @@ -0,0 +1,34 @@ += arg + +== Syntax +@arg { item-description } + +== Description +This command has one argument that continues until the first blank line or until another `@arg` is encountered. The command can be used to generate a simple, not nested list of arguments. Each argument should start with a `@arg` command. + +Equivalent to xref:commands/li.adoc[@li] + + + +*Note:* For nested lists, HTML commands should be used. + +== Example +``` + @arg @c AlignLeft left alignment. + @arg @c AlignCenter center alignment. + @arg @c AlignRight right alignment + + No other types of alignment are supported. + +``` +// [CODE_END] + + +== Rendering +`AlignLeft` left alignment. + +`AlignCenter` center alignment. + +`AlignRight` right alignment + +No other types of alignment are supported. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/attention.adoc b/docs/modules/ROOT/pages/commands/attention.adoc new file mode 100644 index 0000000000..e86f008813 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/attention.adoc @@ -0,0 +1,7 @@ += attention + +== Syntax +@attention { attention text } + +== Description +Starts a paragraph where a message that needs attention may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@attention` commands will be joined into a single paragraph. The `@attention` command ends when a blank line or some other sectioning command is encountered. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/author.adoc b/docs/modules/ROOT/pages/commands/author.adoc new file mode 100644 index 0000000000..e92bed5256 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/author.adoc @@ -0,0 +1,26 @@ += author + +== Syntax +@author { list of authors } + +== Description +Starts a paragraph where one or more author names may be entered. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@author` commands will be joined into a single paragraph. Each author description will start a new line. Alternatively, one `@author` command may mention several authors. The `@author` command ends when a blank line or some other sectioning command is encountered. + +== Example +``` +/*! + * @brief Pretty nice class. + * @details This class is used to demonstrate a number of section commands. + * @author John Doe + * @author Jan Doe + * @version 4.1a + * @date 1990-2011 + * @pre First initialize the system. + * @bug Not all memory is freed when deleting an object of this class. + * @warning Improper use can crash your application + * @copyright GNU Public License. + */ +class SomeNiceClass {}; + +``` +// [CODE_END] diff --git a/docs/modules/ROOT/pages/commands/authors.adoc b/docs/modules/ROOT/pages/commands/authors.adoc new file mode 100644 index 0000000000..d4f8599acd --- /dev/null +++ b/docs/modules/ROOT/pages/commands/authors.adoc @@ -0,0 +1,7 @@ += authors + +== Syntax +@authors { list of authors } + +== Description +Equivalent to xref:commands/author.adoc[@author]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/b.adoc b/docs/modules/ROOT/pages/commands/b.adoc new file mode 100644 index 0000000000..0ff91c4948 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/b.adoc @@ -0,0 +1,7 @@ += b + +== Syntax +@b <word> + +== Description +Displays the argument using a bold font. Equivalent to word. To put multiple words in bold use multiple words. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/brief.adoc b/docs/modules/ROOT/pages/commands/brief.adoc new file mode 100644 index 0000000000..2fb6e99d78 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/brief.adoc @@ -0,0 +1,9 @@ += brief + +== Syntax +@brief { brief description } + +== Description +Starts a paragraph that serves as a brief description. For classes and files the brief description will be used in lists and at the start of the documentation page. For class and file members, the brief description will be placed at the declaration of the member and prepended to the detailed description. A brief description may span several lines (although it is advised to keep it brief!). A brief description ends when a blank line or another sectioning command is encountered. If multiple `@brief` commands are present they will be joined. See section xref:commands/author.adoc[@author] for an example. + +Synonymous to xref:commands/short.adoc[@short]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/bug.adoc b/docs/modules/ROOT/pages/commands/bug.adoc new file mode 100644 index 0000000000..7e36e482d5 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/bug.adoc @@ -0,0 +1,11 @@ += bug + +== Syntax +@bug { bug description } + +== Description +Starts a paragraph where one or more bugs may be reported. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent `@bug` commands will be joined into a single paragraph. Each bug description will start on a new line. Alternatively, one `@bug` command may mention several bugs. The `@bug` command ends when a blank line or some other sectioning command is encountered. See section xref:commands/author.adoc[@author] for an example. + +The description will also add an item to a separate Bug list and the two instances of the description will be cross-referenced. Each item in the Bug list will be preceded by a header that indicates the origin of the item. + +The Bug list and the corresponding entries can be disabled by setting the GENERATE_BUGLIST to `NO`. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/c.adoc b/docs/modules/ROOT/pages/commands/c.adoc new file mode 100644 index 0000000000..491275c240 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/c.adoc @@ -0,0 +1,20 @@ += c + +== Syntax +@c <word> + +== Description +Displays the argument using a typewriter font. Use this to refer to a word of code. Equivalent to word. + +Equivalent to xref:commands/p.adoc[@p]. To have multiple words in typewriter font use multiple words. + +== Example +``` + ... This function returns @c void and not @c int ... + +``` +// [CODE_END] + + +== Rendering +\... This function returns `void` and not `int` ... \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/callergraph.adoc b/docs/modules/ROOT/pages/commands/callergraph.adoc new file mode 100644 index 0000000000..4d83707e7c --- /dev/null +++ b/docs/modules/ROOT/pages/commands/callergraph.adoc @@ -0,0 +1,14 @@ += callergraph + +== Syntax +@callergraph + +== Description +When this command is put in a comment block of a function or method and HAVE_DOT is set to `YES`, then MrDocs will generate a caller graph for that function (provided the implementation of the function or method is called by other documented functions). The caller graph will be generated regardless of the value of CALLER_GRAPH. + + + +*Note:* The completeness (and correctness) of the caller graph depends on the MrDocs code parser which is not perfect. + +== See Also +section xref:commands/callgraph.adoc[@callgraph], section xref:commands/hidecallgraph.adoc[@hidecallgraph], section xref:commands/hidecallergraph.adoc[@hidecallergraph] and option CALLER_GRAPH \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/callgraph.adoc b/docs/modules/ROOT/pages/commands/callgraph.adoc new file mode 100644 index 0000000000..66d2fc0252 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/callgraph.adoc @@ -0,0 +1,14 @@ += callgraph + +== Syntax +@callgraph + +== Description +When this command is put in a comment block of a function or method and HAVE_DOT is set to `YES`, then MrDocs will generate a call graph for that function (provided the implementation of the function or method calls other documented functions). The call graph will be generated regardless of the value of CALL_GRAPH. + + + +*Note:* The completeness (and correctness) of the call graph depends on the MrDocs code parser which is not perfect. + +== See Also +section xref:commands/callergraph.adoc[@callergraph], section xref:commands/hidecallgraph.adoc[@hidecallgraph], section xref:commands/hidecallergraph.adoc[@hidecallergraph] and option CALL_GRAPH \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/category.adoc b/docs/modules/ROOT/pages/commands/category.adoc new file mode 100644 index 0000000000..c1aafd5af5 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/category.adoc @@ -0,0 +1,10 @@ += category + +== Syntax +@category <name> [<header-file>] [<header-name>] + +== Description +For Objective-C only: Indicates that a comment block contains documentation for a class category with name . The arguments are equal to the xref:commands/class.adoc[@class] command. + +== See Also +section xref:commands/class.adoc[@class]. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/commands/cite.adoc b/docs/modules/ROOT/pages/commands/cite.adoc new file mode 100644 index 0000000000..77a2889b76 --- /dev/null +++ b/docs/modules/ROOT/pages/commands/cite.adoc @@ -0,0 +1,7 @@ += cite + +== Syntax +@cite <label> + +== Description +Adds a bibliographic reference in the text and in the list of bibliographic references. The