doc/xmlcmds.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page xmlcmds XML Commands
  18
  19 Doxygen supports most of the XML commands that are typically used in C#
  20 code comments. The XML tags are defined in Appendix D of the
  21 <a href="https://www.ecma-international.org/publications-and-standards/standards/ecma-334/">ECMA-334</a>
  22 standard, which defines the C# language. Unfortunately, the specification is
  23 not very precise and a number of the examples given are of poor quality.
  24
  25 Here is the list of tags supported by doxygen:
  26
  27 <table class="markdownTable">
  28 <tr class="markdownTableHead"><th class="markdownTableHeadLeft">XML Command</th><th class="markdownTableHeadLeft">Description</th></tr>
  29 <tr><td valign="top">\startalign\anchor xmltag_c \addindex "\<c\>"\endalign<tt> \<c\></tt></td><td valign="top">Identifies inline text that should be rendered as a
  30                        piece of code. Similar to using <tt>\<tt\></tt>text<tt>\</tt\></tt>.</td></tr>
  31 <tr><td valign="top">\startalign\anchor xmltag_code \addindex "\<code\>"\endalign<tt> <code\></tt></td><td valign="top">Set one or more lines of source code or program output.
  32                        Note that this command behaves like \ref cmdcode "\\code" ... \ref cmdendcode "\\endcode"
  33                        for C# code, but it behaves like the HTML equivalent
  34                        \ref htmltag_CODE "\<CODE\>"...\ref htmltag_endCODE "\</CODE\>" for other languages.</td></tr>
  35 <tr><td valign="top">\startalign\anchor xmltag_description \addindex "\<description\>"\endalign<tt> \<description\></tt></td><td valign="top">Part of a \ref xmltag_list "\<list\>" command, describes an item.</td></tr>
  36 <tr><td valign="top">\startalign\anchor xmltag_example \addindex "\<example\>"\endalign<tt> \<example\></tt></td><td valign="top">Marks a block of text as an example, ignored by doxygen.</td></tr>
  37 <tr><td valign="top">\startalign\anchor xmltag_exception \addindex "\<exception\>"\endalign<tt> \<exception cref="member"\></tt></td><td valign="top">Identifies the exception a
  38                          method can throw.</td></tr>
  39 <tr><td valign="top">\startalign\anchor xmltag_include \addindex "\<include\>"\endalign<tt> \<include\></tt></td><td valign="top">Can be used to import a piece of XML from an external
  40                          file. Ignored by doxygen at the moment.</td></tr>
  41 <tr><td valign="top">\startalign\anchor xmltag_inheritdoc \addindex "\<inheritdoc\>"\endalign<tt> \<inheritdoc\></tt></td><td valign="top">Can be used to insert the documentation of a
  42                          member of a base class into the documentation of a
  43                          member of a derived class that reimplements it.</td></tr>
  44 <tr><td valign="top">\startalign\anchor xmltag_item \addindex "\<item\>"\endalign<tt> \<item\></tt></td><td valign="top">List item. Can only be used inside a \ref xmltag_list "\<list\>" context.</td></tr>
  45 <tr><td valign="top">\startalign\anchor xmltag_list \addindex "\<list\>"\endalign<tt> \<list type="type"\></tt></td><td valign="top">Starts a list, supported types are <tt>bullet</tt>
  46                          or <tt>number</tt> and <tt>table</tt>.
  47                          A list consists of a number of <tt>\<item\></tt> tags.
  48                          A list of type table, is a two column table which can have
  49                          a header.</td></tr>
  50 <tr><td valign="top">\startalign\anchor xmltag_listheader \addindex "\<listheader\>"\endalign<tt> \<listheader\></tt></td><td valign="top">Starts the header of a list of type "table".</td></tr>
  51 <tr><td valign="top">\startalign\anchor xmltag_para \addindex "\<para\>"\endalign<tt> \<para\></tt></td><td valign="top">Identifies a paragraph of text.</td></tr>
  52 <tr><td valign="top">\startalign\anchor xmltag_param \addindex "\<param\>"\endalign<tt> \<param name="paramName"\></tt></td><td valign="top">Marks a piece of text as the documentation
  53                          for parameter "paramName". Similar to
  54                          using \ref cmdparam "\\param".</td></tr>
  55 <tr><td valign="top">\startalign\anchor xmltag_paramref \addindex "\<paramref\>"\endalign<tt> \<paramref name="paramName"\></tt></td><td valign="top">Refers to a parameter with name
  56                          "paramName". Similar to using \ref cmda "\\a".</td></tr>
  57 <tr><td valign="top">\startalign\anchor xmltag_permission \addindex "\<permission\>"\endalign<tt> \<permission\></tt></td><td valign="top">Identifies the security accessibility of a member.
  58                          Ignored by doxygen.</td></tr>
  59 <tr><td valign="top">\startalign\anchor xmltag_remarks \addindex "\<remarks\>"\endalign<tt> \<remarks\></tt></td><td valign="top">Identifies the detailed description. </td></tr>
  60 <tr><td valign="top">\startalign\anchor xmltag_returns \addindex "\<returns\>"\endalign<tt> \<returns\></tt></td><td valign="top">Marks a piece of text as the return value of a
  61                          function or method. Similar to using \ref cmdreturn "\\return".</td></tr>
  62 <tr><td valign="top">\startalign\anchor xmltag_see \addindex "\<see\>"\endalign<tt> \<see cref="member"\></tt></td><td valign="top">Refers to a member. Similar to \ref cmdref "\\ref".</td></tr>
  63 <tr><td valign="top">\startalign\anchor xmltag_seealso \addindex "\<seealso\>"\endalign<tt> \<seealso cref="member"\></tt></td><td valign="top">Starts a "See also" section referring
  64                          to "member". Similar to using \ref cmdsa "\\sa" member.</td></tr>
  65 <tr><td valign="top">\startalign\anchor xmltag_summary \addindex "\<summary\>"\endalign<tt> \<summary\></tt></td><td valign="top">
  66                          In case this tag is used outside a \ref htmltag_DETAILS "\<DETAILS\>" tag this tag
  67                          identifies the brief description.
  68                          Similar to using \ref cmdbrief "\\brief".
  69                          In case this tag is used inside a \ref htmltag_DETAILS "\<DETAILS\>" tag this tag
  70                          identifies the heading of the \ref htmltag_DETAILS "\<DETAILS\>" tag.</td></tr>
  71 <tr><td valign="top">\startalign\anchor xmltag_term \addindex "\<term\>"\endalign<tt> \<term\></tt></td><td valign="top">Part of a \ref xmltag_list "\<list\>" command.</td></tr>
  72 <tr><td valign="top">\startalign\anchor xmltag_typeparam \addindex "\<typeparam\>"\endalign<tt> \<typeparam name="paramName"\></tt></td><td valign="top">Marks a piece of text as the documentation
  73                          for type parameter "paramName". Similar to
  74                          using \ref cmdparam "\\param".</td></tr>
  75 <tr><td valign="top">\startalign\anchor xmltag_typeparamref \addindex "\<typeparamref\>"\endalign<tt>\<typeparamref name="paramName"\></tt></td><td valign="top">Refers to a parameter with name
  76                          "paramName". Similar to using \ref cmda "\\a".</td></tr>
  77 <tr><td valign="top">\startalign\anchor xmltag_value \addindex "\<value\>"\endalign<tt> \<value\></tt></td><td valign="top">Identifies a property. Ignored by doxygen.</td></tr>
  78 <tr><td valign="top">\startalign\anchor xmltag_CDATA \addindex "\<![CDATA[...]]\>"\endalign<tt> \<![CDATA[...]]\></tt></td><td valign="top">The text inside this tag (on the ...) is  handled as normal
  79                          doxygen comment except for the XML special characters `<`, `>` and
  80                          `&` that are used as if they were escaped.</td></tr>
  81 </table>
  82
  83 Here is an example of a typical piece of code using some of the above commands:
  84
  85 \code
  86 /// <summary>
  87 /// A search engine.
  88 /// </summary>
  89 class Engine
  90 {
  91   /// <summary>
  92   /// The Search method takes a series of parameters to specify the search criterion
  93   /// and returns a dataset containing the result set.
  94   /// </summary>
  95   /// <param name="connectionString">the connection string to connect to the
  96   /// database holding the content to search</param>
  97   /// <param name="maxRows">The maximum number of rows to
  98   /// return in the result set</param>
  99   /// <param name="searchString">The text that we are searching for</param>
 100   /// <returns>A DataSet instance containing the matching rows. It contains a maximum
 101   /// number of rows specified by the maxRows parameter</returns>
 102   public DataSet Search(string connectionString, int maxRows, int searchString)
 103   {
 104     DataSet ds = new DataSet();
 105     return ds;
 106   }
 107 }
 108 \endcode
 109
 110
 111 \htmlonly
 112 Go to the <a href="emojisup.html">next</a> section or return to the
 113  <a href="index.html">index</a>.
 114 \endhtmlonly
 115
 116 */
 117