1mdoc(5)                       File Formats Manual                      mdoc(5)
2
3
4

NAME

6       mdoc - Mono Documentation XML Format
7

DESCRIPTION

9       The  assorted  Mono  documentation  programs generate or manipulate XML
10       files following the mono documentation schema:
11
12       mdoc update
13              Creates or updates mono documentation XML for a  set  of  assem‐
14              blies.
15
16       mdoc validate
17              Validates the mono documentation XML against the mono documenta‐
18              tion XML schema.
19
20       mdoc assemble
21              Converts the mono documentation XML within a directory structure
22              into a set of files for use with monodoc(1).
23
24       mdoc export-html
25              Converts the mono documentation XML within a directory structure
26              into a set of HTML files that can be viewed with a web browser.
27
28       All of these tools (and more) use the common XML  schema  described  in
29       this man page.
30

FILE/DIRECTORY STRUCTURE

32       There are three sets of Mono documentation XML files:
33
34       *      index.xml: contains a list of all assemblies within the contain‐
35              ing directory, and all types and namespaces within those  assem‐
36              blies.
37
38       *      ns-*.xml:  There  is one ns-*.xml file for each namespace within
39              the assembly; these files are siblings to index.xml .
40
41              Examples  of  ns-*.xml  files  include:  ns-System.xml,  ns-Sys‐
42              tem.Collections.xml, and ns-.xml (for the root namespace, though
43              it is recommended to NOT place types into the root namespace, as
44              monodoc(1) doesn't display them).
45
46              The ns-*.xml files contain per-namespace documentation.
47
48       *      NamespaceName/TypeName.xml:  These  files  are  within  a dotted
49              NamespaceName directory, and TypeName is the name of the type.
50
51              Examples include: RootType.xml (if the type has  no  namespace),
52              System/String.xml,  System.Collections/IEnumerable.xml, and Sys‐
53              tem.Collections.Generic/List`1+Enumerator.xml  (the  `1  is  the
54              number  of  generic type parameters the type accepts, and every‐
55              thing after the + is a nested type).
56
57       Thus, typical directory contents would resemble:
58
59           index.xml
60           ns-System.xml
61           ns-System.Collections.Generic.xml
62           System/String.xml
63           System.Collections.Generic/List`1.xml
64

DOCUMENTATION FORMAT

66   index.xml File Format
67       The index.xml file contains a list of the assemblies nested  under  the
68       directory  containing  index.xml  and  all  namespaces and types within
69       those assemblies.  It looks something like this:
70
71           <Overview>
72             <Assemblies>
73               <Assembly Name="mscorlib" Version="2.0.0.0" />
74               <!-- other <Assembly/> elements... -->
75             </Assemblies>
76             <Remarks>To be added.</Remarks>
77             <Copyright>To be added.</Copyright>
78             <Types>
79               <Namespace Name="System">
80                 <Type Name="String" />
81                 <!-- Other <Type/> elements -->
82               </Namespace>
83               <Namespace Name="System.Collections.Generic">
84                 <Type Name="List`1" DisplayName="List&lt;T&gt;" />
85                 <!-- Other <Type/> elements -->
86               </Namespace>
87               <!-- other <Namespace/> elements -->
88             </Types>
89             <Title>DocTest</Title>
90           </Overview>
91
92       Most of this is maintained  automatically,  in  particular  the  /Over‐
93       view/Assemblies and /Overview/Types elements.
94
95       The  //Namespace/@Name  attribute corresponds to a directory which con‐
96       tains  files  named  //Type/@Name.xml,  while  the  //Type/@DisplayName
97       attribute  contains a C# type name (if //Type/@DisplayName isn't found,
98       then //Type/@Name is used as the display name).  There should also be a
99       ns-[//Namespace/@Name].xml file.
100
101       There  are  three  elements  of interest to authors: /Overview/Remarks,
102       /Overview/Copyright, and /Overview/Title, which contain  assembly-level
103       documentation.   These  elements  can  contain any of the following XML
104       elements (documented in the Documentation XML Elements section): block,
105       code, example, list, para, paramref, typeparamref, see, and ul.
106
107   ns-*.xml File Format
108       The ns-*.xml files contain namespace documentation:
109
110           <Namespace Name="System">
111             <Docs>
112               <summary>To be added.</summary>
113               <remarks>To be added.</remarks>
114             </Docs>
115           </Namespace>
116
117       The /Namespace/Docs/summary and /Namespace/Docs/remarks elements should
118       contain namespace documentation.
119
120       The remarks and summary elements are documented  in  the  Documentation
121       XML Elements section.
122
123   NamespaceName/TypeName.xml File Format
124       The mono documentation format is similar to the Ecma documentation for‐
125       mat, as described in ECMA-335 3rd Edition,  Partition  IV,  Chapter  7.
126       The  principal  difference  from the ECMA format is that each type gets
127       its own file, within a directory identical  to  the  namespace  of  the
128       type.   There  is a lot of information that is maintained automatically
129       by mdoc(1); Most of the information within the documentation should not
130       be  edited.  This includes the type name (/Type/@FullName), implemented
131       interfaces (/Type/Interfaces), member  information  (/Type/Members/Mem‐
132       ber/@MemberName,    /Type/Members/Member/MemberSignature,    /Type/Mem‐
133       bers/Member/MemberType, /Type/Members/Member/Parameters, etc.).
134
135           <Type Name="DocAttribute" FullName="Mono.DocTest.DocAttribute">
136             <TypeSignature Language="C#" Value="public class DocAttribute : Attribute" />
137             <AssemblyInfo>
138               <AssemblyName>DocTest</AssemblyName>
139               <AssemblyVersion>0.0.0.0</AssemblyVersion>
140             </AssemblyInfo>
141             <Base>
142               <BaseTypeName>System.Attribute</BaseTypeName>
143             </Base>
144             <Interfaces />
145             <Attributes>
146               <Attribute>
147                 <AttributeName>System.AttributeUsage(System.AttributeTargets.All)</AttributeName>
148               </Attribute>
149             </Attributes>
150             <Docs>
151               <summary>To be added.</summary>
152               <remarks>To be added.</remarks>
153             </Docs>
154             <Members>
155               <Member MemberName=".ctor">
156                 <MemberSignature Language="C#" Value="public DocAttribute (string docs);" />
157                 <MemberType>Constructor</MemberType>
158                 <AssemblyInfo>
159                   <AssemblyVersion>0.0.0.0</AssemblyVersion>
160                 </AssemblyInfo>
161                 <Parameters>
162                   <Parameter Name="docs" Type="System.String" />
163                 </Parameters>
164                 <Docs>
165                   <param name="docs">To be added.</param>
166                   <summary>To be added.</summary>
167                   <remarks>To be added.</remarks>
168                 </Docs>
169               </Member>
170             </Members>
171           </Type>
172
173       The only elements that normally need to be edited are children  of  the
174       //Docs  elements,  which  usually  contain  the  text To be added.  The
175       /Type/Docs  element  contains  type-level  documentation,   while   the
176       /Type/Members/Member/Docs element contains per-member documentation.
177
178       The  //Docs  elements can contain the following elements: altcompliant,
179       altmember, example, exception,  param,  permission,  remarks,  returns,
180       since, summary, threadsafe, typeparam, and value.
181
182       Nested  types  are  not  members; they are types, and are documented in
183       their own file.  Consequently, the NamespaceName/TypeName.xml files are
184       not recursive; you do not store a <Type/> element within a <Type/> ele‐
185       ment.
186
187   Documentation XML Elements
188       The contents of the Docs element is identical in semantics  and  struc‐
189       ture  to  the  inline C# documentation format, consisting of these ele‐
190       ments (listed in ECMA-334 3rd Edition, Annex E, Section 2).   The  fol‐
191       lowing are used within the element descriptions:
192
193       CREF   Refers  to a class (or member) reference, and is a string in the
194              format described below in the CREF FORMAT section.
195
196       TEXT   Non-XML text, and XML should not be nested.
197
198       XML    Only XML elements should be nested (which indirectly may contain
199              text),  but non-whitespace text should not be an immediate child
200              node.
201
202       XML_TEXT
203              Free-form text and XML,  so  that  other  XML  elements  may  be
204              nested.
205
206       The following elements are used in documentation:
207
208       <altmember cref="CREF" />
209              <altmember/>  is  a  top-level  element,  and  should  be nested
210              directly under the <Docs/> element.
211
212              Allows an entry to be generated for the See Also  section.   Use
213              <see/> to specify a link from within text.
214
215                  <altmember cref="P:System.Exception.Message" />
216
217       <block subset="SUBSET" type="TYPE">XML_TEXT</block>
218              Create  a  block of text, similar in concept to a paragraph, but
219              is used to create divisions within the text.  To some extent,  a
220              <block/> is equivalent to the HTML <h2/> tag.
221
222              SUBSET should always be the value "none".
223
224              TYPE  specifies  the  heading and formatting to use.  Recognized
225              types are:
226
227              behaviors Creates a section with the heading Operation.
228
229              note Creates a section with the heading Note:.
230
231              overrides Creates a section with the heading Note to Inheritors.
232
233              usage Creates a section with the heading Usage.
234
235              The block element can contain the following elements: block,  c,
236              code,  list, para, paramref, see, subscript, sup, and typeparam‐
237              ref.
238
239       <c>XML_TEXT</c>
240              Set text in a code-like font (similar to  the  HTML  <tt/>  ele‐
241              ment).
242
243              The  c  element  can contain the following elements: code, para,
244              paramref, see, and typeparamref.
245
246       <code lang="LANGUAGE" src="SOURCE">TEXT</code>
247              Display multiple lines of text in a code-like font  (similar  to
248              the HTML <pre/> element).
249
250              LANGUAGE  is  the language this code block is for.  For example,
251              if LANGUAGE is C#, then TEXT will get  syntax  highlighting  for
252              the C# language within the Mono Documentation Browser.
253
254              SOURCE  is  only  interpreted  by  mdoc-update(1).   If  the src
255              attribute is present when mdoc-update(1) is run, then SOURCE  is
256              a  file  (relative  to  mdoc-update(1)'s  --out  directory) that
257              should be inserted as the value for TEXT.  The contents of  TEXT
258              will  be ignored by mdoc-update(1) and replaced on every invoca‐
259              tion.    SOURCE   can   also   contain   an    "anchor",    e.g.
260              src="path/to/file.cs#RegionMarker".   If  an  anchor is present,
261              and LANGUAGE is C#, then #region RegionMarker will  be  searched
262              for,  and  the  contents  between  the #region and the following
263              #endregion will be inserted as the value for TEXT element.
264
265       <example>XML_TEXT</example>
266              Indicates an example that should be  displayed  specially.   For
267              example:
268
269                  <example>
270                    <para>An introductory paragraph.</para>
271                    <code lang="C#">
272                      class Example {
273                        public static void Main ()
274                        {
275                          System.Console.WriteLine ("Hello, World!");
276                        }
277                      }
278                    </code>
279                  </example>
280
281              The example element can contain the following elements: c, code,
282              list, para, and see.
283
284       <exception cref="CREF">XML_TEXT</exception>
285              Identifies an exception that can be  thrown  by  the  documented
286              member.
287
288              <exception/>  is  a  top-level  element,  and  should  be nested
289              directly under the <Docs/> element.
290
291              CREF is the exception type that is thrown, while  XML_TEXT  con‐
292              tains the circumstances that would cause CREF to be thrown.
293
294                  <exception cref="T:System.ArgumentNullException">
295                    <paramref name="foo" /> was <see langword="null" />.
296                  </exception>
297
298              The exception element can contain the following elements: block,
299              para, paramref, see, and typeparamref.
300
301       <format type="TYPE">XML_TEXT</format>
302              The <format/> element is an "escape hatch," for including  (pos‐
303              sibly  XML) content that is not valid mdoc(5) content.  It's the
304              moral equivalent of perlpod(1) =begin format blocks.
305
306              TYPE is the mime type of XML_TEXT.  mdoc(5) processors may  skip
307              format/> blocks of they use a type that isn't supported.
308
309              For example:
310
311                  <format type="text/html">
312                    <table width="100%">
313                      <tr><td style="color:red">Hello, world!</td></tr>
314                    </table>
315                  </format>
316
317              would  cause  the  embedded HTML <table/> element to be inserted
318              inline into the resulting HTML document when mdoc-export-html(1)
319              processes  the  file.  (Likewise, it may be skipped if processed
320              by another program.)
321
322              format/> is intended to simplify  importing  documentation  from
323              existing  documentation  sources.  It should not be relied upon,
324              if at all possible.
325
326       <list>XML</list>
327              Create a list or table of items.  <list/> makes  use  of  nested
328              <item>XML</item>,                  <listheader>XML</listheader>,
329              <term>XML_TEXT</term>,  and  <description>XML_TEXT</description>
330              elements.
331
332              Lists have the syntax:
333
334                  <list type="bullet"> <!-- or type="number" -->
335                    <item><term>Bullet 1</term></item>
336                    <item><term>Bullet 2</term></item>
337                    <item><term>Bullet 3</term></item>
338                  </list>
339
340              Tables have the syntax:
341
342                  <list type="table">
343                    <listheader> <!-- listheader bolds this row -->
344                      <term>Column 1</term>
345                      <description>Column 2</description>
346                      <description>Column 3</description>
347                    </listheader>
348                    <item>
349                      <term>Item 1-A</term>
350                      <description>Item 1-B</description>
351                      <description>Item 1-C</description>
352                    </item>
353                    <item>
354                      <term>Item 2-A</term>
355                      <description>Item 2-B</description>
356                      <description>Item 2-C</description>
357                    </item>
358                  </list>
359
360              The  item and description elements can each contain text and the
361              following elements: block, c,  para,  paramref,  see,  sup,  and
362              typeparamref.
363
364       <para>XML_TEXT</para>
365              Insert a paragraph of XML_TEXT.  For example,
366
367                  <para>
368                    This is a paragraph of text.
369                  </para>
370
371              The  para  element can contain the following elements: block, c,
372              example, link, list, onequarter, paramref, see, sub, sup,  type‐
373              paramref, and ul.
374
375       <param name="NAME">XML_TEXT</param>
376              <param/>  is  a top-level element, and should be nested directly
377              under the <Docs/> element.
378
379              Describes the parameter NAME of the current constructor, method,
380              or property:
381
382                  <param name="count">
383                    A <see cref="T:System.Int32" /> containing the number
384                    of widgets to process.
385                  </param>
386
387
388              The  param element can contain the following elements: block, c,
389              example, para, paramref, see, and typeparamref.
390
391       <paramref name="NAME" />
392              Indicates that NAME is a parameter.
393
394              This usually renders NAME as italic text, so  it  is  frequently
395              (ab)used  as  an  equivalent  to the HTML <i/> element.  See the
396              <exception/> documentation (above) for an example.
397
398
399       <permission cref="CREF">XML_TEXT</permission>
400              Documents the security accessibility requirements of the current
401              member.
402
403              <permission/>  is  a  top-level  element,  and  should be nested
404              directly under the <Docs/> element.
405
406              CREF is a type reference to the  security  permission  required,
407              while  XML_TEXT  is  a  description  of  why  the  permission is
408              required.
409
410                  <permission cref="T:System.Security.Permissions.FileIOPermission">
411                    Requires permission for reading and writing files. See
412                    <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
413                    <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
414                  </permission>
415
416              The permission  element  can  contain  the  following  elements:
417              block, para, paramref, see, and typeparamref.
418
419       <remarks>XML_TEXT</remarks>
420              Contains detailed information about a member.
421
422              <remarks/> is a top-level element, and should be nested directly
423              under the <Docs/> element.
424
425                  <remarks>
426                    Insert detailed information here.
427                  </remarks>
428
429              The remarks element can contain the following  elements:  block,
430              c, code, example, list, para, paramref, see, and typeparamref.
431
432       <returns>XML_TEXT</returns>
433
434              <returns/> is a top-level element, and should be nested directly
435              under the <Docs/> element.
436
437              Describes the return value of a method:
438
439                  <returns>
440                    A <see cref="T:System.Boolean" /> specifying whether
441                    or not the process can access
442                    <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
443                  </returns>
444
445              The returns element can contain the  following  elements:  list,
446              para, paramref, see, and typeparamref.
447
448       <see cref="CREF" />, <see langword="LANGWORD" />
449              Creates a link to the specified member within the current text:
450
451                  <see cref="M:Some.Namespace.With.Type.Method" />
452
453              or specifies that LANGWORD is a language keyword:
454
455                  <see langword="null" />
456
457
458       <seealso cref="CREF" />
459              Do not use seealso, use altmember.
460
461       <since version="VERSION" />
462
463              <since/>  is  a top-level element, and should be nested directly
464              under the <Docs/> element.
465
466              Permits specification of which version introduced the  specified
467              type or member.
468
469                  <since version="Gtk# 2.4" />
470
471              This  generally  isn't  required,  as  the //AssemblyInfo/Assem‐
472              blyVersion elements track which assembly versions  contain  type
473              or member.
474
475       <summary>XML_TEXT</summary>
476
477              <summary/> is a top-level element, and should be nested directly
478              under the <Docs/> element.
479
480              Provides a (brief!) overview about a type or type member.
481
482              This is usually displayed as part of a  class  declaration,  and
483              should  be  a  reasonably  short description of the type/member.
484              Use <remarks/> for more detailed information.
485
486              The summary element can contain the following  elements:  block,
487              list, para, paramref, see, and typeparamref.
488
489       <typeparam name="NAME">XML_TEXT</typeparam>
490              <typeparam/>  is  a  top-level  element,  and  should  be nested
491              directly under the <Docs/> element.
492
493              This is used to document a type parameter for a generic type  or
494              generic method.
495
496              NAME  is the name of the type parameter, while XML_TEXT contains
497              a description  of  the  parameter  (what  it's  used  for,  what
498              restrictions it must meet, etc.).
499
500                  <typeparam name="T">
501                    The type of the underlying collection
502                  </typeparam>
503
504              The typeparam element can contain the following elements: block,
505              c, para, paramref, see, and typeparamref.
506
507       <typeparamref name="NAME">
508              Used to indicate that NAME is a type parameter.
509
510       <value>XML_TEXT</value>
511              <value/> is a top-level element, and should be  nested  directly
512              under the <Docs/> element.
513
514              Allows a property to be described.
515
516                  <value>
517                    A <see cref="T:System.String" /> containing a widget name.
518                  </value>
519
520              The  value element can contain the following elements: block, c,
521              example, list, para, paramref, see, and typeparamref.
522

CREF FORMAT

524       String IDs (CREFs) are used to refer to a type or  member  of  a  type.
525       String  IDs  are documented in ECMA-334 3rd Edition, Annex E.3.1.  They
526       consist of a member type prefix, the full type name (namespace +  name,
527       separated  by .), possibly followed by the member name and other infor‐
528       mation.
529
530       Member type prefixes:
531
532       C:     The CREF refers to a constructor.  The (optional) parameter list
533              is  enclosed  in  parenthesis  and follows the type name: C:Sys‐
534              tem.String(System.Char,System.Int32).
535
536       E:     The CREF refers to an event.  The event name  follows  the  type
537              name: E:System.AppDomain.AssemblyLoad.
538
539       F:     The  CREF  refers  to  a field.  The field name follows the type
540              name:   F:System.Runtime.InteropServices.DllImportAttribute.Set‐
541              LastError.
542
543       M:     Refers  to  a  constructor  or  method.  Constructors may append
544              .ctor to the type name (instead of using the above C:  construc‐
545              tor  format),  while  methods  append  the  method  name  and an
546              (optional) count of the number of generic parameters.  Both con‐
547              structors  and  methods  may  append  the  method parameter list
548              enclosed in parenthesis.
549
550              Examples:   M:System.Object..ctor,    M:System.String..ctor(Sys‐
551              tem.Char[]),    M:System.String.Concat(System.Object),    M:Sys‐
552              tem.Array.Sort``1(``0[]),                       M:System.Collec‐
553              tions.Generic.List`1..ctor,                     M:System.Collec‐
554              tions.Generic.List`1.Add(`0).
555
556       N:     Refers to a namespace, e.g. N:System.
557
558       P:     Refers to a property.  If the property is an  indexer  or  takes
559              parameters,  the  parameter  types  are appended to the property
560              name  and  enclosed  with  paranthesis:  P:System.String.Length,
561              P:System.String.Chars(System.Int32).
562
563       T:     The  CREF  refers  to  a  type, with the number of generic types
564              appended: T:System.String,  T:System.Collections.Generic.List`1,
565              T:System.Collections.Generic.List`1.Enumerator.
566
567       To make matters more interesting, generic types & members have two rep‐
568       resentations: the "unbound" representation (shown in  examples  above),
569       in  which  class names have the count of generic parameters appended to
570       their name.  There is also a "bound" representation, in which the bind‐
571       ing  of generic parameters is listed within '{' and '}' or '<' and '>'.
572       (Use of '<' and '>' is less common, as within  an  XML  document  their
573       escaped  character entities must instead be used, leading to '&lt;' and
574       '&gt;'.)
575
576       Unbound:
577
578       *      T:System.Collections.Generic.List`1
579
580       *      T:System.Collections.Generic.Dictionary`2
581
582       Bound:
583
584       *      T:System.Collections.Generic.List{System.Int32}
585
586       *      T:System.Collections.Generic.List<System.Int32>
587
588       *      T:System.Collections.Generic.List&lt;System.Int32&gt;
589
590       *      T:System.Predicate{System.Action{System.String}}
591
592       As you can see, bound variants can be arbitrarily  complex  (just  like
593       generics).
594
595       Furthermore,  if  a generic parameter is bound to the generic parameter
596       of a type or method, the "index" of the type/method's generic parameter
597       is used as the binding, so given
598
599           class FooType {
600             public static void Foo<T> (System.Predicate<T> predicate)
601             {
602             }
603           }
604
605       The  CREF  for  this method is M:FooType.Foo``1(System.Predicate{``0}),
606       ``0 is the 0th generic parameter index which is bound to  System.Predi‐
607       cate<T>.
608

SEE ALSO

610       mdoc(1), monodocer(1)
611

MAILING LISTS

613       Visit    http://lists.ximian.com/mailman/listinfo/mono-docs-list    for
614       details.
615

WEB SITE

617       Visit http://www.mono-project.com for details
618
619
620
621                                                                       mdoc(5)
Impressum