mdoc(5) File Formats Manual mdoc(5)
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 assem-
blies.
mdoc validate
Validates the mono documentation XML against the mono documenta-
tion 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 contain-
ing directory, and all types and namespaces within those assem-
blies.
* 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-Sys-
tem.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 Sys-
tem.Collections.Generic/List`1+Enumerator.xml (the `1 is the
number of generic type parameters the type accepts, and every-
thing 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<T>" />
<!-- Other <Type/> elements -->
</Namespace>
<!-- other <Namespace/> elements -->
</Types>
<Title>DocTest</Title>
</Overview>
Most of this is maintained automatically, in particular the /Over-
view/Assemblies and /Overview/Types elements.
The //Namespace/@Name attribute corresponds to a directory which con-
tains files named //Type/@Name.xml, while the //Type/@DisplayName at-
tribute 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 el-
ements (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 for-
mat, 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/Mem-
ber/@MemberName, /Type/Members/Member/MemberSignature, /Type/Mem-
bers/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/> ele-
ment.
Documentation XML Elements
The contents of the Docs element is identical in semantics and struc-
ture to the inline C# documentation format, consisting of these ele-
ments (listed in ECMA-334 3rd Edition, Annex E, Section 2). The fol-
lowing 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 di-
rectly 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 typeparam-
ref.
<c>XML_TEXT</c>
Set text in a code-like font (similar to the HTML <tt/> ele-
ment).
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 attri-
bute 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 #en-
dregion 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 di-
rectly under the <Docs/> element.
CREF is the exception type that is thrown, while XML_TEXT con-
tains 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 (pos-
sibly 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, type-
paramref, 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 di-
rectly 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 re-
quired.
<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, for-
mat, 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/Assem-
blyVersion 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 di-
rectly 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 re-
strictions 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 infor-
mation.
Member type prefixes:
C: The CREF refers to a constructor. The (optional) parameter list
is enclosed in parenthesis and follows the type name: C:Sys-
tem.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.Set-
LastError.
M: Refers to a constructor or method. Constructors may append
.ctor to the type name (instead of using the above C: construc-
tor format), while methods append the method name and an (op-
tional) count of the number of generic parameters. Both con-
structors and methods may append the method parameter list en-
closed in parenthesis.
Examples: M:System.Object..ctor, M:System.String..ctor(Sys-
tem.Char[]), M:System.String.Concat(System.Object), M:System.Ar-
ray.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 parenthesis: P:System.String.Length,
P:System.String.Chars(System.Int32).
T: The CREF refers to a type, with the number of generic types ap-
pended: 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 rep-
resentations: 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 bind-
ing of generic parameters is listed within '{' and '}' or '<' and '>'.
(Use of '<' and '>' is less common, as within an XML document their es-
caped character entities must instead be used, leading to '<' and
'>'.)
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<System.Int32>
* 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.Predi-
cate<T>.
SEE ALSO
mdoc(1), monodocer(1)
MAILING LISTS
Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for de-
tails.
WEB SITE
Visit http://www.mono-project.com for details
mdoc(5)
Generated by dwww version 1.15 on Sun Jun 30 10:25:59 CEST 2024.