11 <table width=
"100%" bgcolor=
"#b0c4da"><tr colspan=
"2"><td>Manual Pages
</td></tr>
12 <tr><td><h3>mdoc(
5)
</h3></td><td align=
"right"></td></tr></table>
13 <h2>NAME
</h2><blockquote>
14 mdoc - Mono Documentation XML Format
15 </blockquote><h2>DESCRIPTION
</h2><blockquote>
16 The assorted Mono documentation programs generate or manipulate XML files
17 following the mono documentation schema:
19 <i>mdoc update
</i></dt><dd>
20 Creates or updates mono documentation XML for a set of assemblies.
22 <i>mdoc validate
</i></dt><dd>
23 Validates the mono documentation XML against the mono documentation XML
26 <i>mdoc assemble
</i></dt><dd>
27 Converts the mono documentation XML within a directory structure into a set
28 of files for use with
<b>monodoc
</b>(
1).
30 <i>mdoc export-html
</i></dt><dd>
31 Converts the mono documentation XML within a directory structure into a set
32 of HTML files that can be viewed with a web browser.
34 All of these tools (and more) use the common XML schema described in this man
36 </p></blockquote><h2>FILE/DIRECTORY STRUCTURE
</h2><blockquote>
37 There are three sets of Mono documentation XML files:
41 contains a list of all assemblies within the containing directory, and all
42 types and namespaces within those assemblies.
46 There is one ns-*.xml file for each namespace within the assembly; these
53 files include:
<i>ns-System.xml
</i>,
<i>ns-System.Collections.xml
</i>, and
54 <i>ns-.xml
</i> (for the root namespace, though it is recommended to NOT place
55 types into the root namespace, as
<b>monodoc
</b>(
1) doesn't display them).
59 files contain per-namespace documentation.
62 <b>NamespaceName/TypeName.xml:
</b>
63 These files are within a dotted
67 is the name of the type.
71 (if the type has no namespace),
72 <i>System/String.xml
</i>,
73 <i>System.Collections/IEnumerable.xml
</i>, and
74 <i>System.Collections.Generic/List`
1+Enumerator.xml
</i>
77 is the number of generic type parameters the type accepts, and everything
82 Thus, typical directory contents would resemble:
88 ns-System.Collections.Generic.xml
90 System.Collections.Generic/List`
1.xml
92 </blockquote><h2>DOCUMENTATION FORMAT
</h2><blockquote>
93 <h3><b>index.xml File Format
</b></h3>
97 file contains a list of the assemblies nested under the directory containing
99 and all namespaces and types within those assemblies. It looks something like
106 <Assembly
Name=
"mscorlib" Version=
"2.0.0.0" /
>
107 <!-- other
<Assembly/
> elements... --
>
109 <Remarks
>To be added.
</Remarks
>
110 <Copyright
>To be added.
</Copyright
>
112 <Namespace
Name=
"System">
113 <Type
Name=
"String" /
>
114 <!-- Other
<Type/
> elements --
>
116 <Namespace
Name=
"System.Collections.Generic">
117 <Type
Name=
"List`1" DisplayName=
"List&lt;T&gt;" /
>
118 <!-- Other
<Type/
> elements --
>
120 <!-- other
<Namespace/
> elements --
>
122 <Title
>DocTest
</Title
>
126 Most of this is maintained automatically, in particular the
127 <i>/Overview/Assemblies
</i>
129 <i>/Overview/Types
</i>
133 <i>//Namespace/@Name
</i>
134 attribute corresponds to a directory which contains files named
135 <i>//Type/@Name
</i>.xml, while the
<i>//Type/@DisplayName
</i> attribute contains
136 a C# type name (if
<i>//Type/@DisplayName
</i> isn't found, then
137 <i>//Type/@Name
</i> is used as the display name). There should also be a
138 <i>ns-[//Namespace/@Name].xml
</i> file.
140 There are three elements of interest to authors:
141 <i>/Overview/Remarks
</i>,
<i>/Overview/Copyright
</i>, and
142 <i>/Overview/Title
</i>, which contain assembly-level documentation.
143 These elements can contain any of the following XML elements (documented in
144 the
<b>Documentation XML Elements
</b> section):
154 <h3><b>ns-*.xml File Format
</b></h3>
155 The
<i>ns-*.xml
</i> files contain namespace documentation:
159 <Namespace
Name=
"System">
161 <summary
>To be added.
</summary
>
162 <remarks
>To be added.
</remarks
>
167 The
<i>/Namespace/Docs/summary
</i> and
<i>/Namespace/Docs/remarks
</i> elements
168 should contain namespace documentation.
170 The
<i>remarks
</i> and
<i>summary
</i> elements are documented in the
171 <b>Documentation XML Elements
</b> section.
172 <h3><b>NamespaceName/TypeName.xml File Format
</b></h3>
174 <i>mono documentation format
</i>
175 is similar to the Ecma documentation format, as described
176 in ECMA-
335 3rd Edition, Partition IV, Chapter
7.
177 The principal difference from the ECMA format is that each type gets its own
178 file, within a directory identical to the namespace of the type. There is a
179 lot of information that is maintained automatically by
<b>mdoc
</b>(
1);
180 Most of the information within the documentation should
182 be edited. This includes the type name (
<i>/Type/@FullName
</i>), implemented
183 interfaces (
<i>/Type/Interfaces
</i>), member information
184 (
<i>/Type/Members/Member/@MemberName
</i>,
185 <i>/Type/Members/Member/MemberSignature
</i>,
186 <i>/Type/Members/Member/MemberType
</i>,
187 <i>/Type/Members/Member/Parameters
</i>, etc.).
191 <Type
Name=
"DocAttribute" FullName=
"Mono.DocTest.DocAttribute">
192 <TypeSignature
Language=
"C#" Value=
"public class DocAttribute : Attribute" /
>
194 <AssemblyName
>DocTest
</AssemblyName
>
195 <AssemblyVersion
>0.0.0.0</AssemblyVersion
>
196 </AssemblyInfo
>
198 <BaseTypeName
>System.Attribute
</BaseTypeName
>
203 <AttributeName
>System.AttributeUsage(System.AttributeTargets.All)
</AttributeName
>
207 <summary
>To be added.
</summary
>
208 <remarks
>To be added.
</remarks
>
211 <Member
MemberName=
".ctor">
212 <MemberSignature
Language=
"C#" Value=
"public DocAttribute (string docs);" /
>
213 <MemberType
>Constructor
</MemberType
>
215 <AssemblyVersion
>0.0.0.0</AssemblyVersion
>
216 </AssemblyInfo
>
218 <Parameter
Name=
"docs" Type=
"System.String" /
>
221 <param
name=
"docs">To be added.
</param
>
222 <summary
>To be added.
</summary
>
223 <remarks
>To be added.
</remarks
>
230 The only elements that normally need to be edited are children of the
231 <i>//Docs
</i> elements, which usually contain the text
233 The
<i>/Type/Docs
</i> element contains type-level documentation, while the
234 <i>/Type/Members/Member/Docs
</i> element contains per-member documentation.
236 The
<i>//Docs
</i> elements can contain the following elements:
248 <i>typeparam
</i>, and
251 Nested types are not members; they are types, and are documented in their own
252 file. Consequently, the
<i>NamespaceName/TypeName.xml
</i> files are not
253 recursive; you do not store a
<i><Type/
></i> element within a
<i><Type/
></i>
255 <h3><b>Documentation XML Elements
</b></h3>
256 The contents of the
<i>Docs
</i> element is
<i>identical
</i>
257 in semantics and structure to the inline C# documentation format, consisting
258 of these elements (listed in ECMA-
334 3rd Edition, Annex E, Section
2). The
259 following are used within the element descriptions:
262 Refers to a class (or member) reference, and is a string in the format
263 described below in the
<b>CREF FORMAT
</b> section.
266 Non-XML text, and XML should not be nested.
270 Only XML elements should be nested (which indirectly may contain text), but
271 non-whitespace text should not be an immediate child node.
273 <i>XML_TEXT
</i></dt><dd>
274 Free-form text and XML, so that other XML elements may be nested.
276 The following elements are used in documentation:
278 <i><altmember
cref=
"CREF" /
></i></dt><dd>
279 <i><altmember/
></i>
280 is a top-level element, and should be nested directly under the
284 Allows an entry to be generated for the
<i>See Also
</i> section. Use
285 <i><see/
></i> to specify a link from within text.
289 <altmember
cref=
"P:System.Exception.Message" /
>
292 <i><block
subset=
"SUBSET" type=
"TYPE">XML_TEXT
</block
></i></dt><dd>
293 Create a block of text, similar in concept to a paragraph, but is used to
294 create divisions within the text. To some extent, a
<block/
> is equivalent to
295 the HTML
<h2/
> tag.
298 should always be the value
<i>"none"</i>.
301 specifies the heading and formatting to use. Recognized types are:
304 Creates a section with the heading
<i>Operation
</i>.
307 Creates a section with the heading
<i>Note:
</i>.
310 Creates a section with the heading
<i>Note to Inheritors
</i>.
313 Creates a section with the heading
<i>Usage
</i>.
315 The
<i>block
</i> element can contain the following elements:
327 <i><c
>XML_TEXT
</c
></i></dt><dd>
328 Set text in a code-like font (similar to the HTML
<tt/
> element).
330 The
<i>c
</i> element can contain the following elements:
337 <i><code
lang=
"LANGUAGE">TEXT
</code
></i></dt><dd>
338 Display multiple lines of text in a code-like font (similar to the HTML
<pre/
>
341 is the language this code block is for. For example, if
<i>LANGUAGE
</i> is
342 <b>C#
</b>, then
<i>TEXT
</i> will get syntax highlighting for the C# language
343 within the Mono Documentation Browser.
345 <i><example
>XML_TEXT
</example
></i></dt><dd>
346 Indicates an example that should be displayed specially. For example:
351 <para
>An introductory paragraph.
</para
>
352 <code
lang=
"C#">
354 public static void Main ()
356 System.Console.WriteLine (
"Hello, World!");
363 The
<i>example
</i> element can contain the following elements:
370 <i><exception
cref=
"CREF">XML_TEXT
</exception
></i></dt><dd>
371 Identifies an exception that can be thrown by the documented member.
373 <i><exception/
></i>
374 is a top-level element, and should be nested directly under the
379 is the exception type that is thrown, while
381 contains the circumstances that would cause
387 <exception
cref=
"T:System.ArgumentNullException">
388 <paramref
name=
"foo" /
> was
<see
langword=
"null" /
>.
392 The
<i>exception
</i> element can contain the following elements:
399 <i><list
>XML
</list
></i></dt><dd>
400 Create a list or table of items.
402 makes use of nested
<i><item
>XML
</item
></i>,
<i><listheader
>XML
</listheader
></i>,
403 <i><term
>XML_TEXT
</term
></i>, and
<i><description
>XML_TEXT
</description
></i>
406 <i>Lists
</i> have the syntax:
410 <list
type=
"bullet"> <!-- or
type=
"number" --
>
411 <item
><term
>Bullet
1</term
></item
>
412 <item
><term
>Bullet
2</term
></item
>
413 <item
><term
>Bullet
3</term
></item
>
422 <list
type=
"table">
423 <listheader
> <!-- listheader bolds this row --
>
424 <term
>Column
1</term
>
425 <description
>Column
2</description
>
426 <description
>Column
3</description
>
429 <term
>Item
1-A
</term
>
430 <description
>Item
1-B
</description
>
431 <description
>Item
1-C
</description
>
434 <term
>Item
2-A
</term
>
435 <description
>Item
2-B
</description
>
436 <description
>Item
2-C
</description
>
441 The
<i>item
</i> and
<i>description
</i> elements can each contain text and
442 the following elements:
451 <i><para
>XML_TEXT
</para
></i></dt><dd>
452 Insert a paragraph of
<i>XML_TEXT
</i>.
458 This is a paragraph of text.
462 The
<i>para
</i> element can contain the following elements:
473 <i>typeparamref
</i>, and
476 <i><param
name=
"NAME">XML_TEXT
</param
></i></dt><dd>
477 <i><param/
></i>
478 is a top-level element, and should be nested directly under the
482 Describes the parameter
<i>NAME
</i> of the current constructor, method, or
487 <param
name=
"count">
488 A
<see
cref=
"T:System.Int32" /
> containing the number
489 of widgets to process.
494 The
<i>param
</i> element can contain the following elements:
503 <i><paramref
name=
"NAME" /
></i></dt><dd>
504 Indicates that
<i>NAME
</i> is a parameter.
506 This usually renders
<i>NAME
</i> as italic text, so it is frequently
507 (ab)used as an equivalent to the HTML
<i/
> element. See the
508 <i><exception/
></i> documentation (above) for an example.
511 <i><permission
cref=
"CREF">XML_TEXT
</permission
></i></dt><dd>
512 Documents the security accessibility requirements of the current member.
514 <i><permission/
></i>
515 is a top-level element, and should be nested directly under the
519 <i>CREF
</i> is a type reference to the security permission required, while
520 <i>XML_TEXT
</i> is a description of why the permission is required.
524 <permission
cref=
"T:System.Security.Permissions.FileIOPermission">
525 Requires permission for reading and writing files. See
526 <see
cref=
"F:System.Security.Permissions.FileIOPermissionAccess.Read" /
>,
527 <see
cref=
"F:System.Security.Permissions.FileIOPermissionAccess.Write" /
>.
531 The
<i>permission
</i> element can contain the following elements:
538 <i><remarks
>XML_TEXT
</remarks
></i></dt><dd>
539 Contains detailed information about a member.
541 <i><remarks/
></i>
542 is a top-level element, and should be nested directly under the
549 Insert detailed information here.
553 The
<i>remarks
</i> element can contain the following elements:
564 <i><returns
>XML_TEXT
</returns
></i></dt><dd>
566 <i><returns/
></i>
567 is a top-level element, and should be nested directly under the
571 Describes the return value of a method:
576 A
<see
cref=
"T:System.Boolean" /
> specifying whether
577 or not the process can access
578 <see
cref=
"P:Mono.Unix.UnixFileSystemInfo.FullName" /
>.
582 The
<i>returns
</i> element can contain the following elements:
589 <i><see
cref=
"CREF" /
></i>,
<i><see
langword=
"LANGWORD" /
></i></dt><dd>
590 Creates a link to the specified member within the current text:
594 <see
cref=
"M:Some.Namespace.With.Type.Method" /
>
597 or specifies that
<i>LANGWORD
</i> is a language keyword:
601 <see
langword=
"null" /
>
605 <i><seealso
cref=
"CREF" /
></i></dt><dd>
606 Do not use
<i>seealso
</i>, use
<i>altmember
</i>.
608 <i><since
version=
"VERSION" /
></i></dt><dd>
610 <i><since/
></i>
611 is a top-level element, and should be nested directly under the
612 <i><Docs/
></i> element.
614 Permits specification of which version introduced the specified type or
619 <since
version=
"Gtk# 2.4" /
>
622 This generally isn't required, as the
<i>//AssemblyInfo/AssemblyVersion
</i>
623 elements track which assembly versions contain type or member.
625 <i><summary
>XML_TEXT
</summary
></i></dt><dd>
627 <i><summary/
></i>
628 is a top-level element, and should be nested directly under the
632 Provides a (brief!) overview about a type or type member.
634 This is usually displayed as part of a class declaration, and should be a
635 reasonably short description of the type/member. Use
636 <i><remarks/
></i>
637 for more detailed information.
639 The
<i>summary
</i> element can contain the following elements:
647 <i><typeparam
name=
"NAME">XML_TEXT
</typeparam
></i></dt><dd>
648 <i><typeparam/
></i>
649 is a top-level element, and should be nested directly under the
653 This is used to document a type parameter for a generic type or generic method.
656 is the name of the type parameter, while
658 contains a description of the parameter (what it's used for, what restrictions
663 <typeparam
name=
"T">
664 The type of the underlying collection
668 The
<i>typeparam
</i> element can contain the following elements:
676 <i><typeparamref
name=
"NAME"></i></dt><dd>
677 Used to indicate that
<i>NAME
</i> is a type parameter.
679 <i><value
>XML_TEXT
</value
></i></dt><dd>
680 <i><value/
></i>
681 is a top-level element, and should be nested directly under the
685 Allows a property to be described.
690 A
<see
cref=
"T:System.String" /
> containing a widget name.
694 The
<i>value
</i> element can contain the following elements:
704 </p></blockquote><h2>CREF FORMAT
</h2><blockquote>
705 String IDs (
<i>CREF
</i>s) are used to refer to a type or member of a type.
706 String IDs are documented in ECMA-
334 3rd Edition, Annex E
.3.1. They consist
707 of a
<i>member type prefix
</i>, the full type name (namespace + name, separated
708 by
<i>.
</i>), possibly followed by the member name and other information.
710 Member type prefixes:
713 The CREF refers to a constructor. The (optional) parameter list is
714 enclosed in parenthesis and follows the type name:
715 <i>C:System.String(System.Char,System.Int32)
</i>.
718 The CREF refers to an event. The event name follows the type name:
719 <i>E:System.AppDomain.AssemblyLoad
</i>.
722 The CREF refers to a field. The field name follows the type name:
723 <i>F:System.Runtime.InteropServices.DllImportAttribute.SetLastError
</i>.
726 Refers to a constructor or method. Constructors may append
728 to the type name (instead of using the above
730 constructor format), while methods append the method name and an (optional)
731 count of the number of generic parameters. Both constructors and methods
732 may append the method parameter list enclosed in parenthesis.
735 <i>M:System.Object..ctor
</i>,
736 <i>M:System.String..ctor(System.Char[])
</i>,
737 <i>M:System.String.Concat(System.Object)
</i>,
738 <i>M:System.Array.Sort``
1(``
0[])
</i>,
739 <i>M:System.Collections.Generic.List`
1..ctor
</i>,
740 <i>M:System.Collections.Generic.List`
1.Add(`
0)
</i>.
743 Refers to a namespace, e.g.
<i>N:System
</i>.
746 Refers to a property. If the property is an indexer or takes parameters,
747 the parameter types are appended to the property name and enclosed with
749 <i>P:System.String.Length
</i>,
750 <i>P:System.String.Chars(System.Int32)
</i>.
753 The CREF refers to a type, with the number of generic types appended:
754 <i>T:System.String
</i>,
755 <i>T:System.Collections.Generic.List`
1</i>,
756 <i>T:System.Collections.Generic.List`
1.Enumerator
</i>.
758 To make matters more interesting, generic types
& members have two
759 representations: the
"unbound" representation (shown in examples above), in
760 which class names have the count of generic parameters appended to their name.
761 There is also a
"bound" representation, in which the binding of generic
762 parameters is listed within '{' and '}' or '
<' and '
>'.
763 (Use of '
<' and '
>' is less common, as within an XML document their escaped
764 character entities must instead be used, leading to '
&lt;' and '
&gt;'.)
769 <i>T:System.Collections.Generic.List`
1</i>
772 <i>T:System.Collections.Generic.Dictionary`
2</i>
777 <i>T:System.Collections.Generic.List{System.Int32}
</i>
780 <i>T:System.Collections.Generic.List
<System.Int32
></i>
783 <i>T:System.Collections.Generic.List
&lt;System.Int32
&gt;
</i>
786 <i>T:System.Predicate{System.Action{System.String}}
</i>
788 As you can see, bound variants can be arbitrarily complex (just like
791 Furthermore, if a generic parameter is bound to the generic parameter of a
792 type or method, the
"index" of the type/method's generic parameter is used
793 as the binding, so given
798 public static void Foo
<T
> (System.Predicate
<T
> predicate)
804 The CREF for this method is
805 <i>M:FooType.Foo``
1(System.Predicate{``
0})
</i>,
807 is the
0th generic parameter index which is bound to
808 <i>System.Predicate
<T
></i>.
809 </blockquote><h2>SEE ALSO
</h2><blockquote>
810 mdoc(
1), monodocer(
1)
811 </blockquote><h2>MAILING LISTS
</h2><blockquote>
813 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
</dt><dd>
814 </dd></dl></blockquote><h2>WEB SITE
</h2><blockquote>
815 Visit http://www.mono-project.com for details