Provided by: monodoc-base_3.2.8+dfsg-4ubuntu1.1_all bug

NAME

       mdoc - Mono Documentation XML Format

DESCRIPTION

       The  assorted  Mono  documentation programs generate or manipulate XML files following the
       mono documentation schema:

       mdoc update
              Creates or updates mono documentation XML for a set of assemblies.

       mdoc validate
              Validates the mono documentation XML against the mono documentation XML schema.

       mdoc assemble
              Converts the mono documentation XML within a directory  structure  into  a  set  of
              files for use with monodoc(1).

       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.

       All of these tools (and more) use the common XML schema described in this man page.

FILE/DIRECTORY STRUCTURE

       There are three sets of Mono documentation XML files:

       *      index.xml: contains a list of all assemblies within the containing  directory,  and
              all types and namespaces within those assemblies.

       *      ns-*.xml:  There is one ns-*.xml file for each namespace within the assembly; these
              files are siblings to index.xml .

              Examples of ns-*.xml files include: ns-System.xml,  ns-System.Collections.xml,  and
              ns-.xml  (for  the root namespace, though it is recommended to NOT place types into
              the root namespace, as monodoc(1) doesn't display them).

              The ns-*.xml files contain per-namespace documentation.

       *      NamespaceName/TypeName.xml:  These  files  are  within   a   dotted   NamespaceName
              directory, and TypeName is the name of the type.

              Examples  include:  RootType.xml (if the type has no namespace), System/String.xml,
              System.Collections/IEnumerable.xml,                                             and
              System.Collections.Generic/List`1+Enumerator.xml  (the  `1 is the number of generic
              type parameters the type accepts, and everything after the + is a nested type).

       Thus, typical directory contents would resemble:

           index.xml
           ns-System.xml
           ns-System.Collections.Generic.xml
           System/String.xml
           System.Collections.Generic/List`1.xml

DOCUMENTATION FORMAT

   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.

CREF FORMAT

       String IDs (CREFs) 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 member type prefix,
       the full type name (namespace + name, separated by .), possibly  followed  by  the  member
       name and other information.

       Member type prefixes:

       C:     The  CREF  refers  to  a constructor.  The (optional) parameter list is enclosed in
              parenthesis and follows the type name: C:System.String(System.Char,System.Int32).

       E:     The  CREF  refers  to  an  event.   The  event  name   follows   the   type   name:
              E:System.AppDomain.AssemblyLoad.

       F:     The   CREF   refers   to   a   field.   The  field  name  follows  the  type  name:
              F:System.Runtime.InteropServices.DllImportAttribute.SetLastError.

       M:     Refers to a constructor or method.  Constructors may append .ctor to the type  name
              (instead of using the above 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.

              Examples:       M:System.Object..ctor,        M:System.String..ctor(System.Char[]),
              M:System.String.Concat(System.Object),               M:System.Array.Sort``1(``0[]),
              M:System.Collections.Generic.List`1..ctor,
              M:System.Collections.Generic.List`1.Add(`0).

       N:     Refers to a namespace, e.g. N:System.

       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  paranthesis:
              P:System.String.Length, P:System.String.Chars(System.Int32).

       T:     The   CREF   refers  to  a  type,  with  the  number  of  generic  types  appended:
              T:System.String,                               T:System.Collections.Generic.List`1,
              T:System.Collections.Generic.List`1.Enumerator.

       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 '&lt;' and '&gt;'.)

       Unbound:

       *      T:System.Collections.Generic.List`1

       *      T:System.Collections.Generic.Dictionary`2

       Bound:

       *      T:System.Collections.Generic.List{System.Int32}

       *      T:System.Collections.Generic.List<System.Int32>

       *      T:System.Collections.Generic.List&lt;System.Int32&gt;

       *      T:System.Predicate{System.Action{System.String}}

       As you can see, bound variants can be arbitrarily complex (just like generics).

       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

           class FooType {
             public static void Foo<T> (System.Predicate<T> predicate)
             {
             }
           }

       The  CREF  for  this  method  is  M:FooType.Foo``1(System.Predicate{``0}),  ``0 is the 0th
       generic parameter index which is bound to System.Predicate<T>.

SEE ALSO

       mdoc(1), monodocer(1)

MAILING LISTS

       Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.

WEB SITE

       Visit http://www.mono-project.com for details

                                                                                          mdoc(5)