FreeBSD Manual Pages
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_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.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)
NAME | DESCRIPTION | FILE/DIRECTORY STRUCTURE | DOCUMENTATION FORMAT | CREF FORMAT | SEE ALSO | MAILING LISTS | WEB SITE
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mdoc&sektion=5&manpath=FreeBSD+13.0-RELEASE+and+Ports>