Man Linux: Main Page and Category List

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)