835 lines
22 KiB
Groff
835 lines
22 KiB
Groff
.\"
|
|
.\" mdoc(5) manual page.
|
|
.\" (C) 2008 Jonathan Pryor
|
|
.\" Author:
|
|
.\" Jonathan Pryor (jpryor@novell.com)
|
|
.\"
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.TH "mdoc" 5
|
|
.SH NAME
|
|
mdoc \- Mono Documentation XML Format
|
|
.SH DESCRIPTION
|
|
The assorted Mono documentation programs generate or manipulate XML files
|
|
following the mono documentation schema:
|
|
.TP
|
|
.I mdoc update
|
|
Creates or updates mono documentation XML for a set of assemblies.
|
|
.TP
|
|
.I mdoc validate
|
|
Validates the mono documentation XML against the mono documentation XML
|
|
schema.
|
|
.TP
|
|
.I mdoc assemble
|
|
Converts the mono documentation XML within a directory structure into a set
|
|
of files for use with \fBmonodoc\fR(1).
|
|
.TP
|
|
.I mdoc export-html
|
|
Converts the mono documentation XML within a directory structure into a set
|
|
of HTML files that can be viewed with a web browser.
|
|
.PP
|
|
All of these tools (and more) use the common XML schema described in this man
|
|
page.
|
|
.SH FILE/DIRECTORY STRUCTURE
|
|
There are three sets of Mono documentation XML files:
|
|
.TP
|
|
.B *
|
|
.B index.xml:
|
|
contains a list of all assemblies within the containing directory, and all
|
|
types and namespaces within those assemblies.
|
|
.TP
|
|
.B *
|
|
.B ns\-*.xml:
|
|
There is one ns-*.xml file for each namespace within the assembly; these
|
|
files are siblings to
|
|
.I index.xml
|
|
\&.
|
|
.Sp
|
|
Examples of
|
|
.I ns\-*.xml
|
|
files include: \fIns-System.xml\fR, \fIns-System.Collections.xml\fR, and
|
|
\fIns-.xml\fR (for the root namespace, though it is recommended to NOT place
|
|
types into the root namespace, as \fBmonodoc\fR(1) doesn't display them).
|
|
.Sp
|
|
The
|
|
.I ns\-*.xml
|
|
files contain per-namespace documentation.
|
|
.TP
|
|
.B *
|
|
.B NamespaceName/TypeName.xml:
|
|
These files are within a dotted
|
|
.I NamespaceName
|
|
directory, and
|
|
.I TypeName
|
|
is the name of the type.
|
|
.Sp
|
|
Examples include:
|
|
.I RootType.xml
|
|
(if the type has no namespace),
|
|
\fISystem/String.xml\fR,
|
|
\fISystem.Collections/IEnumerable.xml\fR, and
|
|
\fISystem.Collections.Generic/List`1+Enumerator.xml\fR
|
|
(the
|
|
.I `1
|
|
is the number of generic type parameters the type accepts, and everything
|
|
after the
|
|
.I +
|
|
is a nested type).
|
|
.PP
|
|
Thus, typical directory contents would resemble:
|
|
|
|
.nf
|
|
index.xml
|
|
ns-System.xml
|
|
ns-System.Collections.Generic.xml
|
|
System/String.xml
|
|
System.Collections.Generic/List`1.xml
|
|
.fi
|
|
.SH DOCUMENTATION FORMAT
|
|
.SS "\fBindex.xml File Format\fR"
|
|
.PP
|
|
The
|
|
.I index.xml
|
|
file contains a list of the assemblies nested under the directory containing
|
|
.I index.xml
|
|
and all namespaces and types within those assemblies. It looks something like
|
|
this:
|
|
|
|
.nf
|
|
<Overview>
|
|
<Assemblies>
|
|
<Assembly Name="mscorlib" Version="2.0.0.0" />
|
|
<!-- other <Assembly/> elements... -->
|
|
</Assemblies>
|
|
<Remarks>To be added.</Remarks>
|
|
<Copyright>To be added.</Copyright>
|
|
<Types>
|
|
<Namespace Name="System">
|
|
<Type Name="String" />
|
|
<!-- Other <Type/> elements -->
|
|
</Namespace>
|
|
<Namespace Name="System.Collections.Generic">
|
|
<Type Name="List`1" DisplayName="List<T>" />
|
|
<!-- Other <Type/> elements -->
|
|
</Namespace>
|
|
<!-- other <Namespace/> elements -->
|
|
</Types>
|
|
<Title>DocTest</Title>
|
|
</Overview>
|
|
.fi
|
|
|
|
Most of this is maintained automatically, in particular the
|
|
.I /Overview/Assemblies
|
|
and
|
|
.I /Overview/Types
|
|
elements.
|
|
.PP
|
|
The
|
|
.I //Namespace/@Name
|
|
attribute corresponds to a directory which contains files named
|
|
\fI//Type/@Name\fR.xml, while the \fI//Type/@DisplayName\fR attribute contains
|
|
a C# type name (if \fI//Type/@DisplayName\fR isn't found, then
|
|
\fI//Type/@Name\fR is used as the display name). There should also be a
|
|
\fIns-[//Namespace/@Name].xml\fR file.
|
|
.PP
|
|
There are three elements of interest to authors:
|
|
\fI/Overview/Remarks\fR, \fI/Overview/Copyright\fR, and
|
|
\fI/Overview/Title\fR, which contain assembly-level documentation.
|
|
These elements can contain any of the following XML elements (documented in
|
|
the \fBDocumentation XML Elements\fR section):
|
|
\fIblock\fR,
|
|
\fIcode\fR,
|
|
\fIexample\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fItypeparamref\fR,
|
|
\fIsee\fR, and
|
|
\fIul\fR.
|
|
.SS "\fBns-*.xml File Format\fR"
|
|
The \fIns-*.xml\fR files contain namespace documentation:
|
|
|
|
.nf
|
|
<Namespace Name="System">
|
|
<Docs>
|
|
<summary>To be added.</summary>
|
|
<remarks>To be added.</remarks>
|
|
</Docs>
|
|
</Namespace>
|
|
.fi
|
|
|
|
The \fI/Namespace/Docs/summary\fR and \fI/Namespace/Docs/remarks\fR elements
|
|
should contain namespace documentation.
|
|
.PP
|
|
The \fIremarks\fR and \fIsummary\fR elements are documented in the
|
|
\fBDocumentation XML Elements\fR section.
|
|
.SS "\fBNamespaceName/TypeName.xml File Format\fR"
|
|
The
|
|
.I mono documentation format
|
|
is similar to the Ecma documentation format, as described
|
|
in ECMA-335 3rd Edition, Partition IV, Chapter 7.
|
|
The principal difference from the ECMA format is that each type gets its own
|
|
file, within a directory identical to the namespace of the type. There is a
|
|
lot of information that is maintained automatically by \fBmdoc\fR(1);
|
|
Most of the information within the documentation should
|
|
.I not
|
|
be edited. This includes the type name (\fI/Type/@FullName\fR), implemented
|
|
interfaces (\fI/Type/Interfaces\fR), member information
|
|
(\fI/Type/Members/Member/@MemberName\fR,
|
|
\fI/Type/Members/Member/MemberSignature\fR,
|
|
\fI/Type/Members/Member/MemberType\fR,
|
|
\fI/Type/Members/Member/Parameters\fR, etc.).
|
|
|
|
.nf
|
|
<Type Name="DocAttribute" FullName="Mono.DocTest.DocAttribute">
|
|
<TypeSignature Language="C#" Value="public class DocAttribute : Attribute" />
|
|
<AssemblyInfo>
|
|
<AssemblyName>DocTest</AssemblyName>
|
|
<AssemblyVersion>0.0.0.0</AssemblyVersion>
|
|
</AssemblyInfo>
|
|
<Base>
|
|
<BaseTypeName>System.Attribute</BaseTypeName>
|
|
</Base>
|
|
<Interfaces />
|
|
<Attributes>
|
|
<Attribute>
|
|
<AttributeName>System.AttributeUsage(System.AttributeTargets.All)</AttributeName>
|
|
</Attribute>
|
|
</Attributes>
|
|
<Docs>
|
|
<summary>To be added.</summary>
|
|
<remarks>To be added.</remarks>
|
|
</Docs>
|
|
<Members>
|
|
<Member MemberName=".ctor">
|
|
<MemberSignature Language="C#" Value="public DocAttribute (string docs);" />
|
|
<MemberType>Constructor</MemberType>
|
|
<AssemblyInfo>
|
|
<AssemblyVersion>0.0.0.0</AssemblyVersion>
|
|
</AssemblyInfo>
|
|
<Parameters>
|
|
<Parameter Name="docs" Type="System.String" />
|
|
</Parameters>
|
|
<Docs>
|
|
<param name="docs">To be added.</param>
|
|
<summary>To be added.</summary>
|
|
<remarks>To be added.</remarks>
|
|
</Docs>
|
|
</Member>
|
|
</Members>
|
|
</Type>
|
|
.fi
|
|
|
|
The only elements that normally need to be edited are children of the
|
|
\fI//Docs\fR elements, which usually contain the text
|
|
.I To be added.
|
|
The \fI/Type/Docs\fR element contains type-level documentation, while the
|
|
\fI/Type/Members/Member/Docs\fR element contains per-member documentation.
|
|
.PP
|
|
The \fI//Docs\fR elements can contain the following elements:
|
|
\fIaltcompliant\fR,
|
|
\fIaltmember\fR,
|
|
\fIexample\fR,
|
|
\fIexception\fR,
|
|
\fIparam\fR,
|
|
\fIpermission\fR,
|
|
\fIremarks\fR,
|
|
\fIreturns\fR,
|
|
\fIsince\fR,
|
|
\fIsummary\fR,
|
|
\fIthreadsafe\fR,
|
|
\fItypeparam\fR, and
|
|
\fIvalue\fR.
|
|
.PP
|
|
Nested types are not members; they are types, and are documented in their own
|
|
file. Consequently, the \fINamespaceName/TypeName.xml\fR files are not
|
|
recursive; you do not store a \fI<Type/>\fR element within a \fI<Type/>\fR
|
|
element.
|
|
.SS "\fBDocumentation XML Elements\fR"
|
|
The contents of the \fIDocs\fR element is \fIidentical\fR
|
|
in semantics and structure to the inline C# documentation format, consisting
|
|
of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2). The
|
|
following are used within the element descriptions:
|
|
.TP
|
|
.I CREF
|
|
Refers to a class (or member) reference, and is a string in the format
|
|
described below in the \fBCREF FORMAT\fR section.
|
|
.TP
|
|
.I TEXT
|
|
Non-XML text, and XML should not be nested.
|
|
.I
|
|
.TP
|
|
.I XML
|
|
Only XML elements should be nested (which indirectly may contain text), but
|
|
non-whitespace text should not be an immediate child node.
|
|
.TP
|
|
.I XML_TEXT
|
|
Free-form text and XML, so that other XML elements may be nested.
|
|
.PP
|
|
The following elements are used in documentation:
|
|
.TP
|
|
.I <altmember cref="CREF" />
|
|
.I <altmember/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
Allows an entry to be generated for the \fISee Also\fR section. Use
|
|
\fI<see/>\fR to specify a link from within text.
|
|
|
|
.nf
|
|
<altmember cref="P:System.Exception.Message" />
|
|
.fi
|
|
.TP
|
|
.I <block subset="SUBSET" type="TYPE">XML_TEXT</block>
|
|
Create a block of text, similar in concept to a paragraph, but is used to
|
|
create divisions within the text. To some extent, a <block/> is equivalent to
|
|
the HTML <h2/> tag.
|
|
.Sp
|
|
.I SUBSET
|
|
should always be the value \fI"none"\fR.
|
|
.Sp
|
|
.I TYPE
|
|
specifies the heading and formatting to use. Recognized types are:
|
|
.Sp
|
|
.I behaviors
|
|
Creates a section with the heading \fIOperation\fR.
|
|
.Sp
|
|
.I note
|
|
Creates a section with the heading \fINote:\fR.
|
|
.Sp
|
|
.I overrides
|
|
Creates a section with the heading \fINote to Inheritors\fR.
|
|
.Sp
|
|
.I usage
|
|
Creates a section with the heading \fIUsage\fR.
|
|
.Sp
|
|
The \fIblock\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIcode\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR,
|
|
\fIsubscript\fR,
|
|
\fIsup\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <c>XML_TEXT</c>
|
|
Set text in a code-like font (similar to the HTML <tt/> element).
|
|
.Sp
|
|
The \fIc\fR element can contain the following elements:
|
|
\fIcode\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <code lang="LANGUAGE" src="SOURCE">TEXT</code>
|
|
Display multiple lines of text in a code-like font (similar to the HTML <pre/>
|
|
element).
|
|
.Sp
|
|
.I LANGUAGE
|
|
is the language this code block is for. For example, if \fILANGUAGE\fR is
|
|
\fBC#\fR, then \fITEXT\fR will get syntax highlighting for the C# language
|
|
within the Mono Documentation Browser.
|
|
.Sp
|
|
.I SOURCE
|
|
is only interpreted by \fBmdoc-update\fR(1). If the \fIsrc\fR attribute is
|
|
present when \fBmdoc-update\fR(1) is run, then \fISOURCE\fR is a file
|
|
(relative to \fBmdoc-update\fR(1)'s \fB--out\fR directory) that
|
|
should be inserted as the value for \fITEXT\fR.
|
|
The contents of \fITEXT\fR will be ignored by \fBmdoc-update\fR(1)
|
|
and replaced on every invocation. \fISOURCE\fR can also contain an "anchor",
|
|
e.g. \fIsrc="path/to/file.cs#RegionMarker"\fR. If an anchor is present,
|
|
\fIand\fR \fILANGUAGE\fR is \fIC#\fR, then \fI#region RegionMarker\fR will be
|
|
searched for, and the contents between the \fI#region\fR and the following
|
|
\fI#endregion\fR will be inserted as the value for \fITEXT\fR element.
|
|
.TP
|
|
.I <example>XML_TEXT</example>
|
|
Indicates an example that should be displayed specially. For example:
|
|
|
|
.nf
|
|
<example>
|
|
<para>An introductory paragraph.</para>
|
|
<code lang="C#">
|
|
class Example {
|
|
public static void Main ()
|
|
{
|
|
System.Console.WriteLine ("Hello, World!");
|
|
}
|
|
}
|
|
</code>
|
|
</example>
|
|
.fi
|
|
|
|
The \fIexample\fR element can contain the following elements:
|
|
\fIc\fR,
|
|
\fIcode\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR, and
|
|
\fIsee\fR.
|
|
.TP
|
|
.I <exception cref="CREF">XML_TEXT</exception>
|
|
Identifies an exception that can be thrown by the documented member.
|
|
.Sp
|
|
.I <exception/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
.I CREF
|
|
is the exception type that is thrown, while
|
|
.I XML_TEXT
|
|
contains the circumstances that would cause
|
|
.I CREF
|
|
to be thrown.
|
|
|
|
.nf
|
|
<exception cref="T:System.ArgumentNullException">
|
|
<paramref name="foo" /> was <see langword="null" />.
|
|
</exception>
|
|
.fi
|
|
|
|
The \fIexception\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <format type="TYPE">XML_TEXT</format>
|
|
The \fI<format/>\fR element is an "escape hatch," for including (possibly XML)
|
|
content that is not valid \fBmdoc\fR(5) content. It's the moral equivalent of
|
|
\fBperlpod\fR(1) \fI=begin format\fR blocks.
|
|
|
|
\fITYPE\fR is the mime type of \fIXML_TEXT\fR. \fBmdoc\fR(5) processors may
|
|
skip \fIformat/>\fR blocks of they use a type that isn't supported.
|
|
|
|
For example:
|
|
|
|
.nf
|
|
<format type="text/html">
|
|
<table width="100%">
|
|
<tr><td style="color:red">Hello, world!</td></tr>
|
|
</table>
|
|
</format>
|
|
.fi
|
|
|
|
would cause the embedded HTML \fI<table/>\fR element to be inserted inline
|
|
into the resulting HTML document when \fBmdoc-export-html\fR(1) processes the
|
|
file. (Likewise, it may be skipped if processed by another program.)
|
|
|
|
\fIformat/>\fR is intended to simplify importing documentation from existing
|
|
documentation sources. It should not be relied upon, if at all possible.
|
|
.TP
|
|
.I <list>XML</list>
|
|
Create a list or table of items.
|
|
.I <list/>
|
|
makes use of nested \fI<item>XML</item>\fR, \fI<listheader>XML</listheader>\fR,
|
|
\fI<term>XML_TEXT</term>\fR, and \fI<description>XML_TEXT</description>\fR
|
|
elements.
|
|
.Sp
|
|
\fILists\fR have the syntax:
|
|
|
|
.nf
|
|
<list type="bullet"> <!-- or type="number" -->
|
|
<item><term>Bullet 1</term></item>
|
|
<item><term>Bullet 2</term></item>
|
|
<item><term>Bullet 3</term></item>
|
|
</list>
|
|
.fi
|
|
.Sp
|
|
.I Tables
|
|
have the syntax:
|
|
|
|
.nf
|
|
<list type="table">
|
|
<listheader> <!-- listheader bolds this row -->
|
|
<term>Column 1</term>
|
|
<description>Column 2</description>
|
|
<description>Column 3</description>
|
|
</listheader>
|
|
<item>
|
|
<term>Item 1-A</term>
|
|
<description>Item 1-B</description>
|
|
<description>Item 1-C</description>
|
|
</item>
|
|
<item>
|
|
<term>Item 2-A</term>
|
|
<description>Item 2-B</description>
|
|
<description>Item 2-C</description>
|
|
</item>
|
|
</list>
|
|
.fi
|
|
|
|
The \fIitem\fR and \fIdescription\fR elements can each contain text and
|
|
the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR,
|
|
\fIsup\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <para>XML_TEXT</para>
|
|
Insert a paragraph of \fIXML_TEXT\fR.
|
|
For example,
|
|
|
|
.nf
|
|
<para>
|
|
This is a paragraph of text.
|
|
</para>
|
|
.fi
|
|
|
|
The \fIpara\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIexample\fR,
|
|
\fIlink\fR,
|
|
\fIlist\fR,
|
|
\fIonequarter\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR,
|
|
\fIsub\fR,
|
|
\fIsup\fR,
|
|
\fItypeparamref\fR, and
|
|
\fIul\fR.
|
|
.TP
|
|
.I <param name="NAME">XML_TEXT</param>
|
|
.I <param/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
Describes the parameter \fINAME\fR of the current constructor, method, or
|
|
property:
|
|
|
|
.nf
|
|
<param name="count">
|
|
A <see cref="T:System.Int32" /> containing the number
|
|
of widgets to process.
|
|
</param>
|
|
.fi
|
|
|
|
|
|
The \fIparam\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIexample\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <paramref name="NAME" />
|
|
Indicates that \fINAME\fR is a parameter.
|
|
.Sp
|
|
This usually renders \fINAME\fR as italic text, so it is frequently
|
|
(ab)used as an equivalent to the HTML <i/> element. See the
|
|
\fI<exception/>\fR documentation (above) for an example.
|
|
.Sp
|
|
.TP
|
|
.I <permission cref="CREF">XML_TEXT</permission>
|
|
Documents the security accessibility requirements of the current member.
|
|
.Sp
|
|
.I <permission/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
\fICREF\fR is a type reference to the security permission required, while
|
|
\fIXML_TEXT\fR is a description of why the permission is required.
|
|
|
|
.nf
|
|
<permission cref="T:System.Security.Permissions.FileIOPermission">
|
|
Requires permission for reading and writing files. See
|
|
<see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
|
|
<see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
|
|
</permission>
|
|
.fi
|
|
|
|
The \fIpermission\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <remarks>XML_TEXT</remarks>
|
|
Contains detailed information about a member.
|
|
.Sp
|
|
.I <remarks/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
|
|
.nf
|
|
<remarks>
|
|
Insert detailed information here.
|
|
</remarks>
|
|
.fi
|
|
|
|
The \fIremarks\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIcode\fR,
|
|
\fIexample\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <returns>XML_TEXT</returns>
|
|
.Sp
|
|
.I <returns/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
Describes the return value of a method:
|
|
|
|
.nf
|
|
<returns>
|
|
A <see cref="T:System.Boolean" /> specifying whether
|
|
or not the process can access
|
|
<see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
|
|
</returns>
|
|
.fi
|
|
|
|
The \fIreturns\fR element can contain the following elements:
|
|
\fIc\fR,
|
|
\fIformat\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
\fI<see cref="CREF" />\fR, \fI<see langword="LANGWORD" />\fR
|
|
Creates a link to the specified member within the current text:
|
|
|
|
.nf
|
|
<see cref="M:Some.Namespace.With.Type.Method" />
|
|
.fi
|
|
|
|
or specifies that \fILANGWORD\fR is a language keyword:
|
|
|
|
.nf
|
|
<see langword="null" />
|
|
.fi
|
|
|
|
.TP
|
|
.I <seealso cref="CREF" />
|
|
Do not use \fIseealso\fR, use \fIaltmember\fR.
|
|
.TP
|
|
.I <since version="VERSION" />
|
|
.Sp
|
|
.I <since/>
|
|
is a top-level element, and should be nested directly under the
|
|
\fI<Docs/>\fR element.
|
|
.Sp
|
|
Permits specification of which version introduced the specified type or
|
|
member.
|
|
|
|
.nf
|
|
<since version="Gtk# 2.4" />
|
|
.fi
|
|
|
|
This generally isn't required, as the \fI//AssemblyInfo/AssemblyVersion\fR
|
|
elements track which assembly versions contain type or member.
|
|
.TP
|
|
.I <summary>XML_TEXT</summary>
|
|
.Sp
|
|
.I <summary/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
Provides a (brief!) overview about a type or type member.
|
|
.Sp
|
|
This is usually displayed as part of a class declaration, and should be a
|
|
reasonably short description of the type/member. Use
|
|
.I <remarks/>
|
|
for more detailed information.
|
|
.Sp
|
|
The \fIsummary\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <typeparam name="NAME">XML_TEXT</typeparam>
|
|
.I <typeparam/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
This is used to document a type parameter for a generic type or generic method.
|
|
.Sp
|
|
.I NAME
|
|
is the name of the type parameter, while
|
|
.I XML_TEXT
|
|
contains a description of the parameter (what it's used for, what restrictions
|
|
it must meet, etc.).
|
|
|
|
.nf
|
|
<typeparam name="T">
|
|
The type of the underlying collection
|
|
</typeparam>
|
|
.fi
|
|
|
|
The \fItypeparam\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.TP
|
|
.I <typeparamref name="NAME">
|
|
Used to indicate that \fINAME\fR is a type parameter.
|
|
.TP
|
|
.I <value>XML_TEXT</value>
|
|
.I <value/>
|
|
is a top-level element, and should be nested directly under the
|
|
.I <Docs/>
|
|
element.
|
|
.Sp
|
|
Allows a property to be described.
|
|
|
|
.nf
|
|
<value>
|
|
A <see cref="T:System.String" /> containing a widget name.
|
|
</value>
|
|
.fi
|
|
|
|
The \fIvalue\fR element can contain the following elements:
|
|
\fIblock\fR,
|
|
\fIc\fR,
|
|
\fIexample\fR,
|
|
\fIlist\fR,
|
|
\fIpara\fR,
|
|
\fIparamref\fR,
|
|
\fIsee\fR, and
|
|
\fItypeparamref\fR.
|
|
.PP
|
|
.SH CREF FORMAT
|
|
String IDs (\fICREF\fRs) are used to refer to a type or member of a type.
|
|
String IDs are documented in ECMA-334 3rd Edition, Annex E.3.1. They consist
|
|
of a \fImember type prefix\fR, the full type name (namespace + name, separated
|
|
by \fI.\fR), possibly followed by the member name and other information.
|
|
.PP
|
|
Member type prefixes:
|
|
.TP
|
|
.I "C:"
|
|
The CREF refers to a constructor. The (optional) parameter list is
|
|
enclosed in parenthesis and follows the type name:
|
|
\fIC:System.String(System.Char,System.Int32)\fR.
|
|
.TP
|
|
.I "E:"
|
|
The CREF refers to an event. The event name follows the type name:
|
|
\fIE:System.AppDomain.AssemblyLoad\fR.
|
|
.TP
|
|
.I "F:"
|
|
The CREF refers to a field. The field name follows the type name:
|
|
\fIF:System.Runtime.InteropServices.DllImportAttribute.SetLastError\fR.
|
|
.TP
|
|
.I "M:"
|
|
Refers to a constructor or method. Constructors may append
|
|
.I .ctor
|
|
to the type name (instead of using the above
|
|
.I C:
|
|
constructor format), while methods append the method name and an (optional)
|
|
count of the number of generic parameters. Both constructors and methods
|
|
may append the method parameter list enclosed in parenthesis.
|
|
.Sp
|
|
Examples:
|
|
\fIM:System.Object..ctor\fR,
|
|
\fIM:System.String..ctor(System.Char[])\fR,
|
|
\fIM:System.String.Concat(System.Object)\fR,
|
|
\fIM:System.Array.Sort``1(``0[])\fR,
|
|
\fIM:System.Collections.Generic.List`1..ctor\fR,
|
|
\fIM:System.Collections.Generic.List`1.Add(`0)\fR.
|
|
.TP
|
|
.I "N:"
|
|
Refers to a namespace, e.g. \fIN:System\fR.
|
|
.TP
|
|
.I "P:"
|
|
Refers to a property. If the property is an indexer or takes parameters,
|
|
the parameter types are appended to the property name and enclosed with
|
|
parenthesis:
|
|
\fIP:System.String.Length\fR,
|
|
\fIP:System.String.Chars(System.Int32)\fR.
|
|
.TP
|
|
.I "T:"
|
|
The CREF refers to a type, with the number of generic types appended:
|
|
\fIT:System.String\fR,
|
|
\fIT:System.Collections.Generic.List`1\fR,
|
|
\fIT:System.Collections.Generic.List`1.Enumerator\fR.
|
|
.PP
|
|
To make matters more interesting, generic types & members have two
|
|
representations: the "unbound" representation (shown in examples above), in
|
|
which class names have the count of generic parameters appended to their name.
|
|
There is also a "bound" representation, in which the binding of generic
|
|
parameters is listed within '{' and '}' or '<' and '>'.
|
|
(Use of '<' and '>' is less common, as within an XML document their escaped
|
|
character entities must instead be used, leading to '<' and '>'.)
|
|
.PP
|
|
.B Unbound:
|
|
.TP
|
|
.B *
|
|
.I T:System.Collections.Generic.List`1
|
|
.TP
|
|
.B *
|
|
.I T:System.Collections.Generic.Dictionary`2
|
|
.PP
|
|
.B Bound:
|
|
.TP
|
|
.B *
|
|
.I T:System.Collections.Generic.List{System.Int32}
|
|
.TP
|
|
.B *
|
|
.I T:System.Collections.Generic.List<System.Int32>
|
|
.TP
|
|
.B *
|
|
.I T:System.Collections.Generic.List<System.Int32>
|
|
.TP
|
|
.B *
|
|
.I T:System.Predicate{System.Action{System.String}}
|
|
.PP
|
|
As you can see, bound variants can be arbitrarily complex (just like
|
|
generics).
|
|
.PP
|
|
Furthermore, if a generic parameter is bound to the generic parameter of a
|
|
type or method, the "index" of the type/method's generic parameter is used
|
|
as the binding, so given
|
|
|
|
.nf
|
|
class FooType {
|
|
public static void Foo<T> (System.Predicate<T> predicate)
|
|
{
|
|
}
|
|
}
|
|
.fi
|
|
|
|
The CREF for this method is
|
|
\fIM:FooType.Foo``1(System.Predicate{``0})\fR,
|
|
.I ``0
|
|
is the 0th generic parameter index which is bound to
|
|
\fISystem.Predicate<T>\fR.
|
|
.SH SEE ALSO
|
|
mdoc(1), monodocer(1)
|
|
.SH MAILING LISTS
|
|
.TP
|
|
Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
|
|
.SH WEB SITE
|
|
Visit http://www.mono-project.com for details
|