1 /******************************************************************************
5 * Copyright (C) 1997-2012 by Dimitri van Heesch.
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.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page xmlcmds XML Commands
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.
25 Here is the list of tags supported by doxygen:
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
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
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.
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.
75 Here is an example of a typical piece of code using some of the above commands:
84 /// The Search method takes a series of parameters to specify the search criterion
85 /// and returns a dataset containing the result set.
87 /// <param name="connectionString">the connection string to connect to the
88 /// database holding the content to search</param>
89 /// <param name="maxRows">The maximum number of rows to
90 /// return in the result set</param>
91 /// <param name="searchString">The text that we are searching for</param>
92 /// <returns>A DataSet instance containing the matching rows. It contains a maximum
93 /// number of rows specified by the maxRows parameter</returns>
94 public DataSet Search(string connectionString, int maxRows, int searchString)
96 DataSet ds = new DataSet();