* MonoDoc XML Tag Reference ** Introduction [This documentation is in progress. Comments to jbarn@httcb.net and/or mono-docs-list@ximian.com.] MonoDoc XML, our format for multilingual API documentation stored outside of source files, is very similar to the output of Microsoft's csc /doc. Minor alterations have been made to ease human parsing and hand-editing, but the majority of the tags are identical. In fact, many of the descriptions and examples below are taken from the ECMA C# Language Specification with little or no alteration. This document provides a list of all available MonoDoc XML tags, with syntax and examples. A complete example can be found in Appendix A, and both a DTD and XSD schema will be available very shortly. ** MonoDoc XML Tags
<c>
<code>
<doc>
<event>
<example>
<exception>
<field>
<list>
<method>
<para>
<param>
<paramref>
<permission>
<property>
<remarks>
<returns>
<see>
<seealso>
<summary>
<type>
<code>
.
**** Syntax
<c>code or output text</c>**** Example
<remarks> Class <c>Point</c> models a point in two-dimensional space. </remarks>*** <code> This tag can be used to mark one or more lines of text as source code or program output. User agents should render this tag in a special (likely monospace) font, and preserve both whitespace and newlines. **** Syntax
<code>source or program output</code>
**** Example
<summary> This method changes the point's location by the given x- and y-offsets. <example lang="C#"> A C# example: <code> Point p = new Point(3, 5); p.Translate(-1, 3); // p == (2, 8); </code> </example> </summary>*** <doc> This tag is the root element of the documentation file. It can contain any number of <type> elements. **** Syntax
<doc lang="language" assembly="assembly">typedocs</doc>
lang="language"**** Example
The two-letter ISO code that specifies what language the contained documentation is written in.
<doc lang="en"> <type name="Graphics.Point"> <!-- ... --> </type> </doc>*** <event> This tag documents an event. **** Syntax
<event name="eventname">documentation</event>
name="eventname"**** Example
The name of the event being documented.
<event name="Click"> <summary> Occurs when the control is clicked. </summary> <data> The event handler receives an argument of type EventArgs containing data related to this event. </data> <remarks> <para>The ControlStyles.StandardClick style must be set for this event to be raised.</para> <para>For more information about handling events, see Consuming Events.</para> </remarks> </event>*** <example> This tag marks a section of text as an example, and optionally specifies what programming language
<code>
portions of the example are written in.
**** Syntax
example text and code
lang="language"**** Example See
(optional) The name of the programming language<code>
blocks in this example use. This information can be used by user agents to provide intelligent access to examples in multiple languages.
<code>
for an example.
*** <exception>
This tag provides a way to specify the exceptions a method can throw.
**** Syntax
<exception cref="exception-type">description</exception>
cref="exception-type"**** Example
The name of an exception type.
<exception cref="System.IO.FileNotFoundException"> Thrown when the requested file is not found. </exception>*** <field> This tag is used to describe a field. **** Syntax
<field name="fieldname">documentation</field>
name="fieldname"**** Example
The name of the field being documented.
<field name="x"> <summary> Instance variable <c>x</c> represents the point's x-coordinate. </summary> </field>*** <list> This tag is used to create a list or table of items. It may contain a
<listheader>
block to define the heading row of either a table or
definition list. (When defining a table, only an entry for 'term' in the
heading need be supplied.)
Each item in the list is specified with an <item>
block. When creating a
definition list, both <term>
and <description>
must be specified.
However, for a table, bulleted list, or numbered list, only <description>
need be specified.
**** Syntax
<list type="bullet" | "number" | "table"> <listheader> <term>term</term> <description>description</description> </listheader> <item> <term>term</term> <description>description</description> </item> ... </list>
term**** Example
The term to define, whose definition is in<description>
.
description
Either an item in a bullet or numbered list, or the definition of a<term>
.
<list type="bullet"> <item> <description>Item 1</description> </item> <item> <description>Item 2</description> </item> </list>*** <method> This tag is the overall containing tag for documenting a method. **** Syntax
<method name="methodname">documentation</method>
**** Example
<method name="op_Equality(Graphics.Point,Graphics.Point)"> <summary> This operator determines whether two points have the same location. </summary> <param name="p1"> <c>p1</c> is the first Point to be compared. </param> <param name="p2"> <c>p2</c> is the second Point to be compared. </param> <returns> True if the points have the same location and they have the exact same type; otherwise, false. </returns> <seealso cref="Equals(System.Object)" /> <seealso cref="op_Inequality(Graphics.Point,Graphics.Point)" /> </method>*** <para> This tag is for use inside other tags such as
<remarks>
or <returns>
, and
allows text to be structured into paragraphs.
**** Syntax
<para>text</para>
**** Example
<summary> <para> This is the entry point of the <c>Point</c> class testing program. </para> <para> This program tests each method and operator, and is intended to be run after any non-trivial maintenance has been performed on the <c>Point</c> class. </para> </summary>*** <param> This tag is used to describe a parameter for a method, constructor, or indexer. **** Syntax
<param name="name">description</param>
name**** Example
The name of the parameter.
<summary> This is the entry point of the <c>Point</c> class. </summary> <param name="xor"><c>xor</c> is the new x-coordinate.</param> <param name "yor"><c>yor</c> is the new y-coordinate.</param>*** <paramref> This tag is used to indicate that a word is a parameter. User agents could use this information for special formatting or hyperlink insertion. **** Syntax
<paramref name="name" />
name**** Example
The name of the parameter.
<summary> This constructor initializes the new Point to (<paramref name="xor" />,<paramref name="yor" />). </summary> <param name="xor"><c>xor</c> is the new x-coordinate.</param> <param name "yor"><c>yor</c> is the new y-coordinate.</param>*** <permission> This tag allows the security accessibility of a member to be documented. **** Syntax
<permission cref="member">description</permission>
cref="member"**** Example
The name of a member.
<permission cref="System.Security.PermissionSet"> Everyone can access this method. </permission>*** <property> This tag is the overall containing tag for documenting a property. **** Syntax
<property name="propertyname">documentation</property>
name="propertyname"**** Example
The name of the property.
<property name="X"> <summary> Gets or sets the point's x-coordinate. <value> The point's x-coordinate. </value> </property>*** <remarks> This tag contains extended discussion and information about a member or a type. [jbarn: This differs from both the ECMA docs and portions of Microsoft's documentation, but seems consistent with both common usage, and, more importantly, NDoc convention.] **** Syntax
<remarks>description</remarks>
**** Example
<type name="Graphics.Point"> <summary> Models a point in a two-dimensional plane. </summary> <remarks> Herein I might have an extended discussion of the validity of Cartesian coordinate systems, with examples pro and con, and perhaps some code. </remarks> <!-- ... --> </type>*** <returns> This tag is used to describe the return value of a method. **** Syntax
<returns>description</returns>
**** Example
<method name="op_Inequality(Graphics.Point,Graphics.Point)"> <summary> This operator determines whether two points have the same location. </summary> <param name="p1"><c>p1</c> is the first Point to be compared.</param> <param name="p2"><c>p2</c> is the second Point to be compared.</param> <returns> True if the points do not have the same location and they have the exact same type; otherwise, false. </returns> </method>*** <see> This tag allows a link to be specified within documentation text. (Use
<seealso>
to indicate links that should appear in a 'See Also' section.)
**** Syntax
<see cref="destination" />
cref="destination"**** Example
A destination, such as a type or a member of a type.
<summary> This method changes the point's location to the given coordinates. This is an asinine way to insert a link, but <see cref="Equals(Object)" /> to understand how points are compared. </summary>*** <seealso> This tag allows an entry to be generated for the 'See Also' section. (Use
<see>
to specify a link from within text.)
**** Syntax
<seealso cref="destination" />
cref="destination"**** Example
A destination, such as a type or a member of a type.
<summary> This method determines whether two Points have the same location. </summary> <seealso cref="op_Equality(Graphics.Point,Graphics.Point)" /> <seealso cref="op_Inequality(Graphics.Point,Graphics.Point" />*** <summary> This tag contains a short summary of a member or type, often one sentence. [jbarn: This differs from both the ECMA docs and portions of Microsoft's documentation, but seems consistent with both common usage, and, more importantly, NDoc convention.] **** Syntax
<summary>description</summary>
**** Example
<summary> This is the entry point of the <c>Point</c> class testing program. </summary> <remarks> This program tests each method an operator, and is intended to be run after any non-trivial maintenance is performed on the <c>Point</c> class. </remarks>*** <type> This tag is the overall containing tag for documenting a type. **** Syntax
<type name="typename" assembly="assemblyname">documentation</type>
name="typename"**** Example
The name of the type being documented.
assembly="assemblyname"
The assembly this type resides in. This attribute is not required for nested types.
<type name="Graphics.Point" assembly="Point"> <summary> Models a point in two-dimensional space. </summary> <!-- members --> <field name="x"> <summary> Represents the point's x-coordinate. </summary> </field> </type>** Appendix A: Complete Example [jbarn: Please, please, don't take the human-readable portions of this example to be good guidelines for writing your own documentation. this XML is intended only to show structure.]
<?xml version="1.0" encoding="UTF-8"?> <doc lang="en"> <type name="Graphics.Point" assembly="Point"> <summary> Models a point in a two-dimensional plane. </summary> <remarks> No useful remarks. </remarks> <!-- fields --> <field name="x"> <summary> Instance variable <c>x</c> represents the point's x-coordinate. </summary> </field> <field name="y"> <summary> Instance variable <c>y</c> represents the point's y-coordinate. </summary> </field> <!-- methods --> <method name="#ctor"> <summary> Initializes the new point to <c>(0,0)</c>. </summary> </method> <method name="#ctor(System.Int32,System.Int32)"> <summary> Initializes the new Point to (<paramref name="xor" />,<paramref name="yor" />). </summary> <param name="xor"><c>xor</c> is the new x-coordinate.</param> <param name="yor"><c>yor</c> is the new y-coordinate.</param> </method> <method name="Move(System.Int32,System.Int32)"> <summary> This method changes the point's location to the given coordinates. </summary> <param name="xor"><c>xor</c> is the new x-coordinate.</param> <param name="yor"><c>yor</c> is the new y-coordinate.</param> <seealso cref="Translate(System.Int32,System.Int32)" /> </method> <method name="Translate(System.Int32,System.Int32)"> <summary>This method changes the point's location by the given x- and y-offsets.</summary> <remarks> <example lang="C#"> A C# example: <code> Point p = new Point(3, 5); p.Translate(-1, 3); </code> This code results in <c>p</c> having the value (2,8). </example> </remarks> <param name="xor"><c>xor</c> is the relative x-offset.</param> <param name="yor"><c>yor</c> is the relative y-offset.</param> <seealso cref="Move(System.Int32,System.Int32)" /> </method> <method name="Equals(System.Object)"> <summary>This method determines whether two points have the same location.</summary> <param name="o"><c>o</c> is the object to be compared to the current object.</param> <returns>True if the Points have the same location and they have the exact same type; otherwise, false.</returns> <seealso cref="op_Equality(Graphics.Point,Graphics.Point)" /> <seealso cref="op_Inequality(Graphics.Point,Graphics.Point" /> </method> <method name="ToString"> <summary>Report a point's location as a string.</summary> <returns>A string representing a point's location, in the form (x,y), without any leading, trailing, or embedded whitespace.</returns> </method> <method name="op_Equality(Graphics.Point,Graphics.Point)"> <summary>This operator determines whether two points have the same location.</summary> <param name="p1"><c>p1</c> is the first Point to be compared.</param> <param name="p2"><c>p2</c> is the second Point to be compared.</param> <returns>True if the points have the same location and they have the exact same type; otherwise, false.</returns> <seealso cref="Equals(System.Object)" /> <seealso cref="op_Inequality(Graphics.Point,Graphics.Point)" /> </method> <method name="op_Inequality(Graphics.Point,Graphics.Point)"> <summary>This operator determines whether two points have the same location.</summary> <param name="p1"><c>p1</c> is the first Point to be compared.</param> <param name="p2"><c>p2</c> is the second Point to be compared.</param> <returns>True if the points do not have the same location and they have the exact same type; otherwise, false.</returns> <seealso cref="Equals(System.Object)" /> <seealso cref="op_Equality(Graphics.Point,Graphics.Point)" /> </method> <method name="Main"> <summary> This is the entry point of the Point class testing program. </summary> <remarks> <para>This program tests each method and operator, and is intended to be run after any non-trivial maintenance has been performed on the Point class.</para> </remarks> </method> <!-- properties --> <property name="X"> <value>Property <c>X</c> represents the point's x-coordinate.</value> </property> <property name="Y"> <value>Property <c>y</c> represents the point's y-coordinate.</value> </property> </type> </doc>