diff options
Diffstat (limited to 'doc/monodoc-xml')
| -rw-r--r-- | doc/monodoc-xml | 755 |
1 files changed, 0 insertions, 755 deletions
diff --git a/doc/monodoc-xml b/doc/monodoc-xml deleted file mode 100644 index e8a5ffe2c71..00000000000 --- a/doc/monodoc-xml +++ /dev/null @@ -1,755 +0,0 @@ -* 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> - |