Provided by: monodoc-base_2.10.5-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: 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)