diff options
Diffstat (limited to 'doc/monodoc-xml')
-rw-r--r-- | doc/monodoc-xml | 755 |
1 files changed, 755 insertions, 0 deletions
diff --git a/doc/monodoc-xml b/doc/monodoc-xml new file mode 100644 index 00000000000..a0b4f11adf5 --- /dev/null +++ b/doc/monodoc-xml @@ -0,0 +1,755 @@ +* MonoDoc XML Tag Reference + +** Introduction + +<em> +[This documentation is in progress. Comments to +<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a> and/or +<a href="mailto:mono-docs-list@ximian.com">mono-docs-list@ximian.com</a>.] +</em> + +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 +<a href="#appendix-a">Appendix A</a>, and both a <a href="#">DTD</a> and +<a href="#">XSD schema</a> will be available very shortly. + +** MonoDoc XML Tags + +<dl> +<dt><code><a href="#c"><c></a></code></dt> +<dd>Mark short sections of text as code.</dd> + +<dt><code><code><a href="#code"><code></a></code></dt></code> +<dd>Mark one or more lines as code or output.</dd> + +<dt><code><a href="#doc"><doc></a></dt></code> +<dd>Root element of documentation XML.</dd> + +<dt><code><a href="#event"><event></a></dt></code> +<dd>Describe an event.</dd> + +<dt><code><a href="#example"><example></a></dt></code> +<dd>An example.</dd> + +<dt><code><a href="#exception"><exception></a></dt></code> +<dd>Specify an exception a method can throw.</dd> + +<dt><code><a href="#field"><field></a></dt></code> +<dd>Describe a field.</dd> + +<dt><code><a href="#list"><list></a></dt></code> +<dd>Create a list or table.</dd> + +<dt><code><a href="#method"><method></a></dt></code> +<dd>Describe a method.</dd> + +<dt><code><a href="#para"><para></a></dt></code> +<dd>Allow text to be structured in paragraphs.</dd> + +<dt><code><a href="#param"><param></a></dt></code> +<dd>Specify a parameter for a method.</dd> + +<dt><code><a href="#paramref"><paramref></a></dt></code> +<dd>Mark a word as a parameter.</dd> + +<dt><code><a href="#permission"><permission></a></dt></code> +<dd>Define the access level of a member.</dd> + +<dt><code><a href="#property"><property></a></dt></code> +<dd>Describe a property.</dd> + +<dt><code><a href="#remarks"><remarks></a></dt></code> +<dd>Provide verbose information for a type or member.</dd> + +<dt><code><a href="#returns"><returns></a></dt></code> +<dd>Specify the return value of a method.</dd> + +<dt><code><a href="#see"><see></a></dt></code> +<dd>Specify a link.</dd> + +<dt><code><a href="#seealso"><seealso></a></dt></code> +<dd>Specify a 'see also' entry.</dd> + +<dt><code><a href="#summary"><summary></a></dt></code> +<dd>Provide a brief (usually one sentence) description of a member or type.</dd> + +<dt><code><a href="#type"><type></a></dt></code> +<dd>Describe a type.</dd> +</dl> + +** Definitions and Examples + +*** <a name="c"><c></a> + +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 <a href="#code"><code><code></code></a>. + +**** Syntax + +<pre> +<c>code or output text</c> +</pre> + +**** Example + +<pre> +<remarks> + Class <c>Point</c> models a point in two-dimensional space. +</remarks> +</pre> + +*** <a name="code"><code></a> + +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><code>source or program output</code></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="doc"><doc></a> + +This tag is the root element of the documentation file. It can contain +any number of <type> elements. + +**** Syntax + +<code><doc lang="language" assembly="assembly">typedocs</doc></code> + +<blockquote> +<em>lang="language"</em><br /> +The two-letter ISO code that specifies what language the contained +documentation is written in. +</blockquote> + +**** Example + +<pre> +<doc lang="en"> + <type name="Graphics.Point"> + <!-- ... --> + </type> +</doc> +</pre> + +*** <a name="event"><event></a> + +This tag documents an event. + +**** Syntax + +<code><event name="eventname">documentation</event></code> + +<blockquote> +<em>name="eventname"</em><br /> +The name of the event being documented. +</blockquote> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="example"><example></a> + +This tag marks a section of text as an example, and optionally specifies +what programming language <code><a href="#code"><code></a></code> portions of the example are written in. + +**** Syntax + +<code><example lang="language">example text and code</example></code> + +<blockquote> +<em>lang="language"</em><br /> +(optional) The name of the programming language <code><a href="#code"><code></a></code> blocks in this example +use. This information can be used by user agents to provide +intelligent access to examples in multiple languages. +</blockquote> + +**** Example + +See <code><a href="#code"><code><a/></code> for an example. + +*** <a name="exception"><exception></a> + +This tag provides a way to specify the exceptions a method can throw. + +**** Syntax + +<code><exception cref="exception-type">description</exception></code> + +<blockquote> +<em>cref="exception-type"</em><br /> +The name of an exception type. +</blockquote> + +**** Example + +<pre> +<exception cref="System.IO.FileNotFoundException"> + Thrown when the requested file is not found. +</exception> +</pre> + +*** <a name="field"><field></a> + +This tag is used to describe a field. + +**** Syntax + +<code><field name="fieldname">documentation</field></code> + +<blockquote> +<em>name="fieldname"</em><br /> +The name of the field being documented. +</blockquote> + +**** Example + +<pre> +<field name="x"> + <summary> + Instance variable <c>x</c> represents the point's + x-coordinate. + </summary> +</field> +</pre> + +*** <a name="list"><list></a> + +This tag is used to create a list or table of items. It may contain a +<code><listheader></code> 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 <code><item></code> block. When creating a +definition list, both <code><term></code> and <code><description></code> must be specified. +However, for a table, bulleted list, or numbered list, only <code><description></code> +need be specified. + +**** Syntax + +<pre> +<list type="bullet" | "number" | "table"> + <listheader> + <term>term</term> + <description>description</description> + </listheader> + <item> + <term>term</term> + <description>description</description> + </item> + + ... + +</list> +</pre> + +<blockquote> +<em>term</em><br /> +The term to define, whose definition is in <code><description></code>. +<br /><br /> +<em>description</em><br /> +Either an item in a bullet or numbered list, or the definition of a <code><term></code>. +</blockquote> + +**** Example + +<pre> +<list type="bullet"> + <item> + <description>Item 1</description> + </item> + <item> + <description>Item 2</description> + </item> +</list> +</pre> + +*** <a name="method"><method></a> + +This tag is the overall containing tag for documenting a method. + +**** Syntax + +<code><method name="methodname">documentation</method></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="para"><para></a> + + +This tag is for use inside other tags such as <code><remarks></code> or <code><returns></code>, and +allows text to be structured into paragraphs. + +**** Syntax + +<code><para>text</para></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="param"><param></a> + +This tag is used to describe a parameter for a method, constructor, or +indexer. + +**** Syntax + +<code><param name="name">description</param></code> + +<blockquote> +<em>name</em><br /> +The name of the parameter. +</blockquote> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="paramref"><paramref></a> + +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 + +<code><paramref name="name" /></code> + +<blockquote> +<em>name</em><br /> +The name of the parameter. +</blockquote> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="permission"><permission></a> + +This tag allows the security accessibility of a member to be documented. + +**** Syntax + +<code><permission cref="member">description</permission></code> + +<blockquote> +<em>cref="member"</em><br /> +The name of a member.</br> +</blockquote> + +**** Example + +<pre> +<permission cref="System.Security.PermissionSet"> + Everyone can access this method. +</permission> +</pre> + +*** <a name="property"><property></a> + +This tag is the overall containing tag for documenting a property. + +**** Syntax + +<code><property name="propertyname">documentation</property></code> + +<blockquote> +<em>name="propertyname"</em><br /> +The name of the property. +</blockquote> + +**** Example + +<pre> +<property name="X"> + <summary> + Gets or sets the point's x-coordinate. + <value> + The point's x-coordinate. + </value> +</property> +</pre> + + +*** <a name="remarks"><remarks></a> + +This tag contains extended discussion and information about a member or +a type. <em>[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.]</em> + +**** Syntax + +<code><remarks>description</remarks></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="returns"><returns></a> + +This tag is used to describe the return value of a method. + +**** Syntax + +<code><returns>description</returns></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="see"><see></a> + +This tag allows a link to be specified within documentation text. (Use +<code><seealso></code> to indicate links that should appear in a 'See Also' section.) + +**** Syntax + +<code><see cref="destination" /></code> + +<blockquote> +<em>cref="destination"</em><br /> +A destination, such as a type or a member of a type. +</blockquote> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="seealso"><seealso></a> + +This tag allows an entry to be generated for the 'See Also' section. (Use +<code><see></code> to specify a link from within text.) + +**** Syntax + +<code><seealso cref="destination" /></code> + +<blockquote> +<em>cref="destination"</em><br /> +A destination, such as a type or a member of a type. +</blockquote> + +**** Example + +<pre> +<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" /> +</pre> + +*** <a name="summary"><summary></a> + +This tag contains a short summary of a member or type, +often one sentence. <em>[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.]</em> + +**** Syntax + +<code><summary>description</summary></code> + +**** Example + +<pre> +<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> +</pre> + +*** <a name="type"><type></a> + +This tag is the overall containing tag for documenting a type. + +**** Syntax + +<code><type name="typename" assembly="assemblyname">documentation</type></code> + +<blockquote> +<em>name="typename"</em><br /> +The name of the type being documented. +<br /><br /> +<em>assembly="assemblyname"</em><br /> +The assembly this type resides in. This attribute is not required for nested types. +</blockquote> + +**** Example + +<pre> +<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> +</pre> + +** <a name="appendix-a">Appendix A: Complete Example</a> + +<em>[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.</em> + +<pre> +<?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> +</pre> + |