diff options
author | Jonathan Pryor <jpryor@novell.com> | 2008-10-18 23:20:48 +0400 |
---|---|---|
committer | Jonathan Pryor <jpryor@novell.com> | 2008-10-18 23:20:48 +0400 |
commit | b5fc24ea887d41897182e18c578f9001202dfd17 (patch) | |
tree | a602ed9ba1dffba3353486dbb58086720c80de32 /man/mdoc.5 | |
parent | 6a985c22b158bf484cbc0f1be9ce2d410c80f2b9 (diff) |
Migrating from monodoc/man to mono/man...
svn path=/trunk/mono/; revision=116386
Diffstat (limited to 'man/mdoc.5')
-rw-r--r-- | man/mdoc.5 | 794 |
1 files changed, 794 insertions, 0 deletions
diff --git a/man/mdoc.5 b/man/mdoc.5 new file mode 100644 index 00000000000..bcf1268212e --- /dev/null +++ b/man/mdoc.5 @@ -0,0 +1,794 @@ +.\" +.\" mdoc(5) manual page. +.\" (C) 2008 Jonathan Pryor +.\" Author: +.\" Jonathan Pryor (jpryor@novell.com) +.\" +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.TH "mdoc" 5 +.SH NAME +mdoc \- Mono Documentation XML Format +.SH DESCRIPTION +The assorted Mono documentation programs generate or manipulate XML files +following the mono documentation schema: +.TP +.I mdoc update +Creates or updates mono documentation XML for a set of assemblies. +.TP +.I mdoc validate +Validates the mono documentation XML against the mono documentation XML +schema. +.TP +.I mdoc assemble +Converts the mono documentation XML within a directory structure into a set +of files for use with \fBmonodoc\fR(1). +.TP +.I 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. +.PP +All of these tools (and more) use the common XML schema described in this man +page. +.SH FILE/DIRECTORY STRUCTURE +There are three sets of Mono documentation XML files: +.TP +.B * +.B index.xml: +contains a list of all assemblies within the containing directory, and all +types and namespaces within those assemblies. +.TP +.B * +.B ns\-*.xml: +There is one ns-*.xml file for each namespace within the assembly; these +files are siblings to +.I index.xml +\&. +.Sp +Examples of +.I ns\-*.xml +files include: \fIns-System.xml\fR, \fIns-System.Collections.xml\fR, and +\fIns-.xml\fR (for the root namespace, though it is recommended to NOT place +types into the root namespace, as \fBmonodoc\fR(1) doesn't display them). +.Sp +The +.I ns\-*.xml +files contain per-namespace documentation. +.TP +.B * +.B NamespaceName/TypeName.xml: +These files are within a dotted +.I NamespaceName +directory, and +.I TypeName +is the name of the type. +.Sp +Examples include: +.I RootType.xml +(if the type has no namespace), +\fISystem/String.xml\fR, +\fISystem.Collections/IEnumerable.xml\fR, and +\fISystem.Collections.Generic/List`1+Enumerator.xml\fR +(the +.I `1 +is the number of generic type parameters the type accepts, and everything +after the +.I + +is a nested type). +.PP +Thus, typical directory contents would resemble: + +.nf + index.xml + ns-System.xml + ns-System.Collections.Generic.xml + System/String.xml + System.Collections.Generic/List`1.xml +.fi +.SH DOCUMENTATION FORMAT +.SS "\fBindex.xml File Format\fR" +.PP +The +.I index.xml +file contains a list of the assemblies nested under the directory containing +.I index.xml +and all namespaces and types within those assemblies. It looks something like +this: + +.nf + <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> +.fi + +Most of this is maintained automatically, in particular the +.I /Overview/Assemblies +and +.I /Overview/Types +elements. +.PP +The +.I //Namespace/@Name +attribute corresponds to a directory which contains files named +\fI//Type/@Name\fR.xml, while the \fI//Type/@DisplayName\fR attribute contains +a C# type name (if \fI//Type/@DisplayName\fR isn't found, then +\fI//Type/@Name\fR is used as the display name). There should also be a +\fIns-[//Namespace/@Name].xml\fR file. +.PP +There are three elements of interest to authors: +\fI/Overview/Remarks\fR, \fI/Overview/Copyright\fR, and +\fI/Overview/Title\fR, which contain assembly-level documentation. +These elements can contain any of the following XML elements (documented in +the \fBDocumentation XML Elements\fR section): +\fIblock\fR, +\fIcode\fR, +\fIexample\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fItypeparamref\fR, +\fIsee\fR, and +\fIul\fR. +.SS "\fBns-*.xml File Format\fR" +The \fIns-*.xml\fR files contain namespace documentation: + +.nf + <Namespace Name="System"> + <Docs> + <summary>To be added.</summary> + <remarks>To be added.</remarks> + </Docs> + </Namespace> +.fi + +The \fI/Namespace/Docs/summary\fR and \fI/Namespace/Docs/remarks\fR elements +should contain namespace documentation. +.PP +The \fIremarks\fR and \fIsummary\fR elements are documented in the +\fBDocumentation XML Elements\fR section. +.SS "\fBNamespaceName/TypeName.xml File Format\fR" +The +.I 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 \fBmdoc\fR(1); +Most of the information within the documentation should +.I not +be edited. This includes the type name (\fI/Type/@FullName\fR), implemented +interfaces (\fI/Type/Interfaces\fR), member information +(\fI/Type/Members/Member/@MemberName\fR, +\fI/Type/Members/Member/MemberSignature\fR, +\fI/Type/Members/Member/MemberType\fR, +\fI/Type/Members/Member/Parameters\fR, etc.). + +.nf + <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> +.fi + +The only elements that normally need to be edited are children of the +\fI//Docs\fR elements, which usually contain the text +.I To be added. +The \fI/Type/Docs\fR element contains type-level documentation, while the +\fI/Type/Members/Member/Docs\fR element contains per-member documentation. +.PP +The \fI//Docs\fR elements can contain the following elements: +\fIaltcompliant\fR, +\fIaltmember\fR, +\fIexample\fR, +\fIexception\fR, +\fIparam\fR, +\fIpermission\fR, +\fIremarks\fR, +\fIreturns\fR, +\fIsince\fR, +\fIsummary\fR, +\fIthreadsafe\fR, +\fItypeparam\fR, and +\fIvalue\fR. +.PP +Nested types are not members; they are types, and are documented in their own +file. Consequently, the \fINamespaceName/TypeName.xml\fR files are not +recursive; you do not store a \fI<Type/>\fR element within a \fI<Type/>\fR +element. +.SS "\fBDocumentation XML Elements\fR" +The contents of the \fIDocs\fR element is \fIidentical\fR +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: +.TP +.I CREF +Refers to a class (or member) reference, and is a string in the format +described below in the \fBCREF FORMAT\fR section. +.TP +.I TEXT +Non-XML text, and XML should not be nested. +.I +.TP +.I XML +Only XML elements should be nested (which indirectly may contain text), but +non-whitespace text should not be an immediate child node. +.TP +.I XML_TEXT +Free-form text and XML, so that other XML elements may be nested. +.PP +The following elements are used in documentation: +.TP +.I <altmember cref="CREF" /> +.I <altmember/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +Allows an entry to be generated for the \fISee Also\fR section. Use +\fI<see/>\fR to specify a link from within text. + +.nf + <altmember cref="P:System.Exception.Message" /> +.fi +.TP +.I <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. +.Sp +.I SUBSET +should always be the value \fI"none"\fR. +.Sp +.I TYPE +specifies the heading and formatting to use. Recognized types are: +.Sp +.I behaviors +Creates a section with the heading \fIOperation\fR. +.Sp +.I note +Creates a section with the heading \fINote:\fR. +.Sp +.I overrides +Creates a section with the heading \fINote to Inheritors\fR. +.Sp +.I usage +Creates a section with the heading \fIUsage\fR. +.Sp +The \fIblock\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIcode\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, +\fIsubscript\fR, +\fIsup\fR, and +\fItypeparamref\fR. +.TP +.I <c>XML_TEXT</c> +Set text in a code-like font (similar to the HTML <tt/> element). +.Sp +The \fIc\fR element can contain the following elements: +\fIcode\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <code lang="LANGUAGE">TEXT</code> +Display multiple lines of text in a code-like font (similar to the HTML <pre/> +element). +.I LANGUAGE +is the language this code block is for. For example, if \fILANGUAGE\fR is +\fBC#\fR, then \fITEXT\fR will get syntax highlighting for the C# language +within the Mono Documentation Browser. +.TP +.I <example>XML_TEXT</example> +Indicates an example that should be displayed specially. For example: + +.nf + <example> + <para>An introductory paragraph.</para> + <code lang="C#"> + class Example { + public static void Main () + { + System.Console.WriteLine ("Hello, World!"); + } + } + </code> + </example> +.fi + +The \fIexample\fR element can contain the following elements: +\fIc\fR, +\fIcode\fR, +\fIlist\fR, +\fIpara\fR, and +\fIsee\fR. +.TP +.I <exception cref="CREF">XML_TEXT</exception> +Identifies an exception that can be thrown by the documented member. +.Sp +.I <exception/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +.I CREF +is the exception type that is thrown, while +.I XML_TEXT +contains the circumstances that would cause +.I CREF +to be thrown. + +.nf + <exception cref="T:System.ArgumentNullException"> + <paramref name="foo" /> was <see langword="null" />. + </exception> +.fi + +The \fIexception\fR element can contain the following elements: +\fIblock\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <list>XML</list> +Create a list or table of items. +.I <list/> +makes use of nested \fI<item>XML</item>\fR, \fI<listheader>XML</listheader>\fR, +\fI<term>XML_TEXT</term>\fR, and \fI<description>XML_TEXT</description>\fR +elements. +.Sp +\fILists\fR have the syntax: + +.nf + <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> +.fi +.Sp +.I Tables +have the syntax: + +.nf + <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> +.fi + +The \fIitem\fR and \fIdescription\fR elements can each contain text and +the following elements: +\fIblock\fR, +\fIc\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, +\fIsup\fR, and +\fItypeparamref\fR. +.TP +.I <para>XML_TEXT</para> +Insert a paragraph of \fIXML_TEXT\fR. +For example, + +.nf + <para> + This is a paragraph of text. + </para> +.fi + +The \fIpara\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIexample\fR, +\fIlink\fR, +\fIlist\fR, +\fIonequarter\fR, +\fIparamref\fR, +\fIsee\fR, +\fIsub\fR, +\fIsup\fR, +\fItypeparamref\fR, and +\fIul\fR. +.TP +.I <param name="NAME">XML_TEXT</param> +.I <param/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +Describes the parameter \fINAME\fR of the current constructor, method, or +property: + +.nf + <param name="count"> + A <see cref="T:System.Int32" /> containing the number + of widgets to process. + </param> +.fi + + +The \fIparam\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIexample\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <paramref name="NAME" /> +Indicates that \fINAME\fR is a parameter. +.Sp +This usually renders \fINAME\fR as italic text, so it is frequently +(ab)used as an equivalent to the HTML <i/> element. See the +\fI<exception/>\fR documentation (above) for an example. +.Sp +.TP +.I <permission cref="CREF">XML_TEXT</permission> +Documents the security accessibility requirements of the current member. +.Sp +.I <permission/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +\fICREF\fR is a type reference to the security permission required, while +\fIXML_TEXT\fR is a description of why the permission is required. + +.nf + <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> +.fi + +The \fIpermission\fR element can contain the following elements: +\fIblock\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <remarks>XML_TEXT</remarks> +Contains detailed information about a member. +.Sp +.I <remarks/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. + +.nf + <remarks> + Insert detailed information here. + </remarks> +.fi + +The \fIremarks\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIcode\fR, +\fIexample\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <returns>XML_TEXT</returns> +.Sp +.I <returns/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +Describes the return value of a method: + +.nf + <returns> + A <see cref="T:System.Boolean" /> specifying whether + or not the process can access + <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />. + </returns> +.fi + +The \fIreturns\fR element can contain the following elements: +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +\fI<see cref="CREF" />\fR, \fI<see langword="LANGWORD" />\fR +Creates a link to the specified member within the current text: + +.nf + <see cref="M:Some.Namespace.With.Type.Method" /> +.fi + +or specifies that \fILANGWORD\fR is a language keyword: + +.nf + <see langword="null" /> +.fi + +.TP +.I <seealso cref="CREF" /> +Do not use \fIseealso\fR, use \fIaltmember\fR. +.TP +.I <since version="VERSION" /> +.Sp +.I <since/> +is a top-level element, and should be nested directly under the +\fI<Docs/>\fR element. +.Sp +Permits specification of which version introduced the specified type or +member. + +.nf + <since version="Gtk# 2.4" /> +.fi + +This generally isn't required, as the \fI//AssemblyInfo/AssemblyVersion\fR +elements track which assembly versions contain type or member. +.TP +.I <summary>XML_TEXT</summary> +.Sp +.I <summary/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +Provides a (brief!) overview about a type or type member. +.Sp +This is usually displayed as part of a class declaration, and should be a +reasonably short description of the type/member. Use +.I <remarks/> +for more detailed information. +.Sp +The \fIsummary\fR element can contain the following elements: +\fIblock\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <typeparam name="NAME">XML_TEXT</typeparam> +.I <typeparam/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +This is used to document a type parameter for a generic type or generic method. +.Sp +.I NAME +is the name of the type parameter, while +.I XML_TEXT +contains a description of the parameter (what it's used for, what restrictions +it must meet, etc.). + +.nf + <typeparam name="T"> + The type of the underlying collection + </typeparam> +.fi + +The \fItypeparam\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.TP +.I <typeparamref name="NAME"> +Used to indicate that \fINAME\fR is a type parameter. +.TP +.I <value>XML_TEXT</value> +.I <value/> +is a top-level element, and should be nested directly under the +.I <Docs/> +element. +.Sp +Allows a property to be described. + +.nf + <value> + A <see cref="T:System.String" /> containing a widget name. + </value> +.fi + +The \fIvalue\fR element can contain the following elements: +\fIblock\fR, +\fIc\fR, +\fIexample\fR, +\fIlist\fR, +\fIpara\fR, +\fIparamref\fR, +\fIsee\fR, and +\fItypeparamref\fR. +.PP +.SH CREF FORMAT +String IDs (\fICREF\fRs) 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 \fImember type prefix\fR, the full type name (namespace + name, separated +by \fI.\fR), possibly followed by the member name and other information. +.PP +Member type prefixes: +.TP +.I "C:" +The CREF refers to a constructor. The (optional) parameter list is +enclosed in parenthesis and follows the type name: +\fIC:System.String(System.Char,System.Int32)\fR. +.TP +.I "E:" +The CREF refers to an event. The event name follows the type name: +\fIE:System.AppDomain.AssemblyLoad\fR. +.TP +.I "F:" +The CREF refers to a field. The field name follows the type name: +\fIF:System.Runtime.InteropServices.DllImportAttribute.SetLastError\fR. +.TP +.I "M:" +Refers to a constructor or method. Constructors may append +.I .ctor +to the type name (instead of using the above +.I 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. +.Sp +Examples: +\fIM:System.Object..ctor\fR, +\fIM:System.String..ctor(System.Char[])\fR, +\fIM:System.String.Concat(System.Object)\fR, +\fIM:System.Array.Sort``1(``0[])\fR, +\fIM:System.Collections.Generic.List`1..ctor\fR, +\fIM:System.Collections.Generic.List`1.Add(`0)\fR. +.TP +.I "N:" +Refers to a namespace, e.g. \fIN:System\fR. +.TP +.I "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: +\fIP:System.String.Length\fR, +\fIP:System.String.Chars(System.Int32)\fR. +.TP +.I "T:" +The CREF refers to a type, with the number of generic types appended: +\fIT:System.String\fR, +\fIT:System.Collections.Generic.List`1\fR, +\fIT:System.Collections.Generic.List`1.Enumerator\fR. +.PP +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 '<' and '>'.) +.PP +.B Unbound: +.TP +.B * +.I T:System.Collections.Generic.List`1 +.TP +.B * +.I T:System.Collections.Generic.Dictionary`2 +.PP +.B Bound: +.TP +.B * +.I T:System.Collections.Generic.List{System.Int32} +.TP +.B * +.I T:System.Collections.Generic.List<System.Int32> +.TP +.B * +.I T:System.Collections.Generic.List<System.Int32> +.TP +.B * +.I T:System.Predicate{System.Action{System.String}} +.PP +As you can see, bound variants can be arbitrarily complex (just like +generics). +.PP +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 + +.nf + class FooType { + public static void Foo<T> (System.Predicate<T> predicate) + { + } + } +.fi + +The CREF for this method is +\fIM:FooType.Foo``1(System.Predicate{``0})\fR, +.I ``0 +is the 0th generic parameter index which is bound to +\fISystem.Predicate<T>\fR. +.SH SEE ALSO +mdoc(1), monodocer(1) +.SH MAILING LISTS +.TP +Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details. +.SH WEB SITE +Visit http://www.mono-project.com for details |