Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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&lt;T&gt;" />
		 <!-- 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
       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 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
	      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 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
	      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 invoca-
	      tion.    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  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
	      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: 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
	      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	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
	      (optional) count of the number of	generic	parameters.  Both con-
	      structors	 and  methods  may  append  the	 method	parameter list
	      enclosed in parenthesis.

	      Examples:	  M:System.Object..ctor,    M:System.String..ctor(Sys-
	      tem.Char[]),    M:System.String.Concat(System.Object),	M:Sys-
	      tem.Array.Sort``1(``0[]),			      M:System.Collec-
	      tions.Generic.List`1..ctor,		      M:System.Collec-
	      tions.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 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
       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.Predi-
       cate_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)

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://www.freebsd.org/cgi/man.cgi?query=mdoc&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help