* 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>: Mark short sections of text as code.
<code>: Mark one or more lines as code or output.
<doc>: Root element of documentation XML.
<event>: Describe an event.
<example>: An example.
<exception>: Specify an exception a method can throw.
<field>: Describe a field.
<list>: Create a list or table.
<method>: Describe a method.
<para>: Allow text to be structured in paragraphs.
<param>: Specify a parameter for a method.
<paramref>: Mark a word as a parameter.
<permission>: Define the access level of a member.
<property>: Describe a property.
<remarks>: Provide verbose information for a type or member.
<returns>: Specify the return value of a method.
<see>: Specify a link.
<seealso>: Specify a 'see also' entry.
<summary>: Provide a brief (usually one sentence) description of a member or type.
<type>: Describe a type.

** Definitions and Examples *** <c> This tag can be used to mark short, inline fragments of text that should be considered source code or program output. User agents should render this tag in a special -- likely monospace -- font. For larger sections, use <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"
The two-letter ISO code that specifies what language the contained documentation is written in.

**** Example

<doc lang="en">
    <type name="Graphics.Point">
        <!-- ... -->
    </type>
</doc>

*** <event> This tag documents an event. **** Syntax <event name="eventname">documentation</event>

name="eventname"
The name of the event being documented.

**** Example

<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"
(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.

**** Example See <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"
The name of an exception type.

**** Example

<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"
The name of the field being documented.

**** Example

<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
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>.

**** Example

<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
The name of the parameter.

**** Example

<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
The name of the parameter.

**** Example

<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"
The name of a member.

**** Example

<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"
The name of the property.

**** Example

<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"
A destination, such as a type or a member of a type.

**** Example

<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"
A destination, such as a type or a member of a type.

**** Example

<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"
The name of the type being documented.

assembly="assemblyname"
The assembly this type resides in. This attribute is not required for nested types.

**** Example

<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>