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 E of the
  21 <a href="http://www.ecma-international.org/publications/standards/Ecma-334.htm">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 <ul>
  28 <li><tt>\<c\></tt>     Identifies inline text that should be rendered as a
  29                        piece of code. Similar to using <tt>\<tt\></tt>text<tt>\</tt\></tt>.
  30 <li><tt>\<code\></tt>  Set one or more lines of source code or program output.
  31                        Note that this command behaves like \ref cmdcode "\\code" ... \ref cmdendcode "\\endcode"
  32                        for C# code, but it behaves like the HTML equivalent
  33                        <tt>\<code\>...\</code\></tt> for other languages.
  34 <li><tt>\<description\></tt> Part of a <tt>\<list\></tt> command, describes an item.
  35 <li><tt>\<example\></tt> Marks a block of text as an example, ignored by doxygen.
  36 <li><tt>\<exception cref="member"\></tt> Identifies the exception a
  37                          method can throw.
  38 <li><tt>\<include\></tt> Can be used to import a piece of XML from an external
  39                          file. Ignored by doxygen at the moment.
  40 <li><tt>\<inheritdoc\></tt> Can be used to insert the documentation of a
  41                          member of a base class into the documentation of a
  42                          member of a derived class that reimplements it.
  43 <li><tt>\<item\></tt> List item. Can only be used inside a <tt>\<list\></tt> context.
  44 <li><tt>\<list type="type"\></tt> Starts a list, supported types are <tt>bullet</tt>
  45                          or <tt>number</tt> and <tt>table</tt>.
  46                          A list consists of a number of <tt>\<item\></tt> tags.
  47                          A list of type table, is a two column table which can have
  48                          a header.
  49 <li><tt>\<listheader\></tt>   Starts the header of a list of type "table".
  50 <li><tt>\<para\></tt>    Identifies a paragraph of text.
  51 <li><tt>\<param name="paramName"\></tt> Marks a piece of text as the documentation
  52                          for parameter "paramName". Similar to
  53                          using \ref cmdparam "\\param".
  54 <li><tt>\<paramref name="paramName"\></tt> Refers to a parameter with name
  55                          "paramName". Similar to using \ref cmda "\\a".
  56 <li><tt>\<permission\></tt> Identifies the security accessibility of a member.
  57                          Ignored by doxygen.
  58 <li><tt>\<remarks\></tt> Identifies the detailed description.
  59 <li><tt>\<returns\></tt> Marks a piece of text as the return value of a
  60                          function or method. Similar to using \ref cmdreturn "\\return".
  61 <li><tt>\<see cref="member"\></tt> Refers to a member. Similar to \ref cmdref "\\ref".
  62 <li><tt>\<seealso cref="member"\></tt> Starts a "See also" section referring
  63                          to "member". Similar to using \ref cmdsa "\\sa" member.
  64 <li><tt>\<summary\></tt> Identifies the brief description.
  65                          Similar to using \ref cmdbrief "\\brief".
  66 <li><tt>\<term\></tt>    Part of a <tt>\<list\></tt> command.
  67 <li><tt>\<typeparam name="paramName"\></tt> Marks a piece of text as the documentation
  68                          for type parameter "paramName". Similar to
  69                          using \ref cmdparam "\\param".
  70 <li><tt>\<typeparamref name="paramName"\></tt> Refers to a parameter with name
  71                          "paramName". Similar to using \ref cmda "\\a".
  72 <li><tt>\<value\></tt>   Identifies a property. Ignored by doxygen.
  73 <li><tt>\<![CDATA[...]]\></tt> The text inside this tag (on the ...) is  handled as normal
  74                          doxygen comment except for the XML special characters `<`, `>` and
  75                          `&` that are used as if they were escaped.
  76 </ul>
  77
  78 Here is an example of a typical piece of code using some of the above commands:
  79
  80 \code
  81 /// <summary>
  82 /// A search engine.
  83 /// </summary>
  84 class Engine
  85 {
  86   /// <summary>
  87   /// The Search method takes a series of parameters to specify the search criterion
  88   /// and returns a dataset containing the result set.
  89   /// </summary>
  90   /// <param name="connectionString">the connection string to connect to the
  91   /// database holding the content to search</param>
  92   /// <param name="maxRows">The maximum number of rows to
  93   /// return in the result set</param>
  94   /// <param name="searchString">The text that we are searching for</param>
  95   /// <returns>A DataSet instance containing the matching rows. It contains a maximum
  96   /// number of rows specified by the maxRows parameter</returns>
  97   public DataSet Search(string connectionString, int maxRows, int searchString)
  98   {
  99     DataSet ds = new DataSet();
 100     return ds;
 101   }
 102 }
 103 \endcode
 104
 105
 106 \htmlonly
 107 Go to the <a href="emojisup.html">next</a> section or return to the
 108  <a href="index.html">index</a>.
 109 \endhtmlonly
 110
 111 */
 112