index.xml File Format¶

The index.xml file contains a list of the assemblies nested under the directory containing index.xml and all namespaces and types within those assemblies. It looks something like this:

    <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&lt;T&gt;" />


          <!-- Other <Type/> elements -->


        </Namespace>


        <!-- other <Namespace/> elements -->


      </Types>


      <Title>DocTest</Title>


    </Overview>

Most of this is maintained automatically, in particular the /Overview/Assemblies and /Overview/Types elements.

The //Namespace/@Name attribute corresponds to a directory which contains files named //Type/@Name.xml, while the //Type/@DisplayName attribute contains a C# type name (if //Type/@DisplayName isn't found, then //Type/@Name is used as the display name). There should also be a ns-[//Namespace/@Name].xml file.

There are three elements of interest to authors: /Overview/Remarks, /Overview/Copyright, and /Overview/Title, which contain assembly-level documentation. These elements can contain any of the following XML elements (documented in the Documentation XML Elements section): block, code, example, list, para, paramref, typeparamref, see, and ul.

ns-*.xml File Format¶

The ns-*.xml files contain namespace documentation:

    <Namespace Name="System">


      <Docs>


        <summary>To be added.</summary>


        <remarks>To be added.</remarks>


      </Docs>


    </Namespace>

The /Namespace/Docs/summary and /Namespace/Docs/remarks elements should contain namespace documentation.

The remarks and summary elements are documented in the Documentation XML Elements section.

NamespaceName/TypeName.xml File Format¶

The 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 mdoc(1); Most of the information within the documentation should not be edited. This includes the type name (/Type/@FullName), implemented interfaces (/Type/Interfaces), member information (/Type/Members/Member/@MemberName, /Type/Members/Member/MemberSignature, /Type/Members/Member/MemberType, /Type/Members/Member/Parameters, etc.).

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

The only elements that normally need to be edited are children of the //Docs elements, which usually contain the text To be added. The /Type/Docs element contains type-level documentation, while the /Type/Members/Member/Docs element contains per-member documentation.

The //Docs elements can contain the following elements: altcompliant, altmember, example, exception, param, permission, remarks, returns, since, summary, threadsafe, typeparam, and value.

Nested types are not members; they are types, and are documented in their own file. Consequently, the NamespaceName/TypeName.xml files are not recursive; you do not store a <Type/> element within a <Type/> element.

Documentation XML Elements¶

The contents of the Docs element is identical 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:

CREF

Refers to a class (or member) reference, and is a string in the format described below in the CREF FORMAT section.

TEXT

Non-XML text, and XML should not be nested.

XML

Only XML elements should be nested (which indirectly may contain text), but non-whitespace text should not be an immediate child node.

XML_TEXT

Free-form text and XML, so that other XML elements may be nested.

The following elements are used in documentation:

<altmember cref="CREF" />

<altmember/> is a top-level element, and should be nested directly under the <Docs/> element.

Allows an entry to be generated for the See Also section. Use <see/> to specify a link from within text.

    <altmember cref="P:System.Exception.Message" />

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

SUBSET should always be the value "none".

TYPE specifies the heading and formatting to use. Recognized types are:

behaviors Creates a section with the heading Operation.

note Creates a section with the heading Note:.

overrides Creates a section with the heading Note to Inheritors.

usage Creates a section with the heading Usage.

The block element can contain the following elements: block, c, code, list, para, paramref, see, subscript, sup, and typeparamref.

<c>XML_TEXT</c>

Set text in a code-like font (similar to the HTML <tt/> element).

The c element can contain the following elements: code, para, paramref, see, and typeparamref.

<code lang="LANGUAGE" src="SOURCE">TEXT</code>

Display multiple lines of text in a code-like font (similar to the HTML <pre/> element).

LANGUAGE is the language this code block is for. For example, if LANGUAGE is C#, then TEXT will get syntax highlighting for the C# language within the Mono Documentation Browser.

SOURCE is only interpreted by mdoc-update(1). If the src attribute is present when mdoc-update(1) is run, then SOURCE is a file (relative to mdoc-update(1)'s --out directory) that should be inserted as the value for TEXT. The contents of TEXT will be ignored by mdoc-update(1) and replaced on every invocation. SOURCE can also contain an "anchor", e.g. src="path/to/file.cs#RegionMarker". If an anchor is present, and LANGUAGE is C#, then #region RegionMarker will be searched for, and the contents between the #region and the following #endregion will be inserted as the value for TEXT element.

<example>XML_TEXT</example>

Indicates an example that should be displayed specially. For example:

    <example>


      <para>An introductory paragraph.</para>


      <code lang="C#">


        class Example {


          public static void Main ()


          {


            System.Console.WriteLine ("Hello, World!");


          }


        }


      </code>


    </example>

The example element can contain the following elements: c, code, list, para, and see.

<exception cref="CREF">XML_TEXT</exception>

Identifies an exception that can be thrown by the documented member.

<exception/> is a top-level element, and should be nested directly under the <Docs/> element.

CREF is the exception type that is thrown, while XML_TEXT contains the circumstances that would cause CREF to be thrown.

    <exception cref="T:System.ArgumentNullException">


      <paramref name="foo" /> was <see langword="null" />.


    </exception>

The exception element can contain the following elements: block, para, paramref, see, and typeparamref.

<format type="TYPE">XML_TEXT</format>

The <format/> element is an "escape hatch," for including (possibly XML) content that is not valid mdoc(5) content. It's the moral equivalent of perlpod(1) =begin format blocks.

TYPE is the mime type of XML_TEXT. mdoc(5) processors may skip format/> blocks of they use a type that isn't supported.

For example:

    <format type="text/html">


      <table width="100%">


        <tr><td style="color:red">Hello, world!</td></tr>


      </table>


    </format>

would cause the embedded HTML <table/> element to be inserted inline into the resulting HTML document when mdoc-export-html(1) processes the file. (Likewise, it may be skipped if processed by another program.)

format/> is intended to simplify importing documentation from existing documentation sources. It should not be relied upon, if at all possible.

<list>XML</list>

Create a list or table of items. <list/> makes use of nested <item>XML</item>, <listheader>XML</listheader>, <term>XML_TEXT</term>, and <description>XML_TEXT</description> elements.

Lists have the syntax:

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

Tables have the syntax:

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

The item and description elements can each contain text and the following elements: block, c, para, paramref, see, sup, and typeparamref.

<para>XML_TEXT</para>

Insert a paragraph of XML_TEXT. For example,

    <para>


      This is a paragraph of text.


    </para>

The para element can contain the following elements: block, c, example, link, list, onequarter, paramref, see, sub, sup, typeparamref, and ul.

<param name="NAME">XML_TEXT</param>

<param/> is a top-level element, and should be nested directly under the <Docs/> element.

Describes the parameter NAME of the current constructor, method, or property:

    <param name="count">


      A <see cref="T:System.Int32" /> containing the number


      of widgets to process.


    </param>

The param element can contain the following elements: block, c, example, para, paramref, see, and typeparamref.

<paramref name="NAME" />

Indicates that NAME is a parameter.

This usually renders NAME as italic text, so it is frequently (ab)used as an equivalent to the HTML <i/> element. See the <exception/> documentation (above) for an example.

<permission cref="CREF">XML_TEXT</permission>

Documents the security accessibility requirements of the current member.

<permission/> is a top-level element, and should be nested directly under the <Docs/> element.

CREF is a type reference to the security permission required, while XML_TEXT is a description of why the permission is required.

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

The permission element can contain the following elements: block, para, paramref, see, and typeparamref.

<remarks>XML_TEXT</remarks>

Contains detailed information about a member.

<remarks/> is a top-level element, and should be nested directly under the <Docs/> element.

    <remarks>


      Insert detailed information here.


    </remarks>

The remarks element can contain the following elements: block, c, code, example, list, para, paramref, see, and typeparamref.

<returns>XML_TEXT</returns>

<returns/> is a top-level element, and should be nested directly under the <Docs/> element.

Describes the return value of a method:

    <returns>


      A <see cref="T:System.Boolean" /> specifying whether 


      or not the process can access 


      <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.


    </returns>

The returns element can contain the following elements: c, format, list, para, paramref, see, and typeparamref.

<see cref="CREF" />, <see langword="LANGWORD" />

Creates a link to the specified member within the current text:

    <see cref="M:Some.Namespace.With.Type.Method" />

or specifies that LANGWORD is a language keyword:

    <see langword="null" />

<seealso cref="CREF" />

Do not use seealso, use altmember.

<since version="VERSION" />

<since/> is a top-level element, and should be nested directly under the <Docs/> element.

Permits specification of which version introduced the specified type or member.

    <since version="Gtk# 2.4" />

This generally isn't required, as the //AssemblyInfo/AssemblyVersion elements track which assembly versions contain type or member.

<summary>XML_TEXT</summary>

<summary/> is a top-level element, and should be nested directly under the <Docs/> element.

Provides a (brief!) overview about a type or type member.

This is usually displayed as part of a class declaration, and should be a reasonably short description of the type/member. Use <remarks/> for more detailed information.

The summary element can contain the following elements: block, list, para, paramref, see, and typeparamref.

<typeparam name="NAME">XML_TEXT</typeparam>

<typeparam/> is a top-level element, and should be nested directly under the <Docs/> element.

This is used to document a type parameter for a generic type or generic method.

NAME is the name of the type parameter, while XML_TEXT contains a description of the parameter (what it's used for, what restrictions it must meet, etc.).

    <typeparam name="T">


      The type of the underlying collection


    </typeparam>

The typeparam element can contain the following elements: block, c, para, paramref, see, and typeparamref.

<typeparamref name="NAME">

Used to indicate that NAME is a type parameter.

<value>XML_TEXT</value>

<value/> is a top-level element, and should be nested directly under the <Docs/> element.

Allows a property to be described.

    <value>


      A <see cref="T:System.String" /> containing a widget name.


    </value>

The value element can contain the following elements: block, c, example, list, para, paramref, see, and typeparamref.