1 /******************************************************************************

     2  *

     3  * 

     4  *

     5  * Copyright (C) 1997-2008 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 <tt>\\code ... \\endcode</tt>

    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>\<item\></tt> List item. Can only be used inside a <tt>\<list\></tt> context.

    41 <li><tt>\<list type="type"\></tt> Starts a list, supported types are <tt>bullet</tt>

    42                          or <tt>number</tt> and <tt>table</tt>. 

    43                          A list consists of a number of <tt>\<item\></tt> tags.

    44                          A list of type table, is a two column table which can have

    45                          a header.

    46 <li><tt>\<listheader\></tt>   Starts the header of a list of type "table".

    47 <li><tt>\<para\></tt>    Identifies a paragraph of text.

    48 <li><tt>\<param name="paramName"\></tt> Marks a piece of text as the documentation

    49                          for parameter "paramName". Similar to 

    50                          using \ref cmdparam "\\param".

    51 <li><tt>\<paramref name="paramName"\></tt> Refers to a parameter with name

    52                          "paramName". Similar to using \ref cmda "\\a".

    53 <li><tt>\<permission\></tt> Identifies the security accessibility of a member.

    54                          Ignored by doxygen.

    55 <li><tt>\<remarks\></tt> Identifies the detailed description. 

    56 <li><tt>\<returns\></tt> Marks a piece of text as the return value of a

    57                          function or method. Similar to using \ref cmdreturn "\\return".

    58 <li><tt>\<see cref="member"\></tt> Refers to a member. Similar to \ref cmdref "\\ref".

    59 <li><tt>\<seealso cref="member"\></tt> Starts a "See also" section referring

    60                          to "member". Similar to using \ref cmdsa "\\sa" member.

    61 <li><tt>\<summary\></tt> Identifies the brief description.

    62                          Similar to using \ref cmdbrief "\\brief".

    63 <li><tt>\<term\></tt>    Part of a <tt>\<list\></tt> command.

    64 <li><tt>\<typeparam name="paramName"\></tt> Marks a piece of text as the documentation

    65                          for type parameter "paramName". Similar to 

    66                          using \ref cmdparam "\\param".

    67 <li><tt>\<typeparamref name="paramName"\></tt> Refers to a parameter with name

    68                          "paramName". Similar to using \ref cmda "\\a".

    69 <li><tt>\<value\></tt>   Identifies a property. Ignored by doxygen.

    70 </ul>

    71 

    72 Here is an example of a typical piece of code using some of the above commands:

    73 

    74 \code

    75 /// <summary>

    76 /// A search engine.

    77 /// </summary>

    78 class Engine

    79 {

    80   /// <summary>

    81   /// The Search method takes a series of parameters to specify the search criterion

    82   /// and returns a dataset containing the result set.

    83   /// </summary>

    84   /// <param name="connectionString">the connection string to connect to the

    85   /// database holding the content to search</param>

    86   /// <param name="maxRows">The maximum number of rows to

    87   /// return in the result set</param>

    88   /// <param name="searchString">The text that we are searching for</param>

    89   /// <returns>A DataSet instance containing the matching rows. It contains a maximum

    90   /// number of rows specified by the maxRows parameter</returns>

    91   public DataSet Search(string connectionString, int maxRows, int searchString)

    92   {

    93     DataSet ds = new DataSet();

    94     return ds;

    95   }

    96 }

    97 \endcode

    98 

    99 */

   100