man/mdoc.5

   1 .\"
   2 .\" mdoc(5) manual page.
   3 .\" (C) 2008 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jpryor@novell.com)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "mdoc" 5
  12 .SH NAME
  13 mdoc \- Mono Documentation XML Format
  14 .SH DESCRIPTION
  15 The assorted Mono documentation programs generate or manipulate XML files
  16 following the mono documentation schema:
  17 .TP
  18 .I mdoc update
  19 Creates or updates mono documentation XML for a set of assemblies.
  20 .TP
  21 .I mdoc validate
  22 Validates the mono documentation XML against the mono documentation XML
  23 schema.
  24 .TP
  25 .I mdoc assemble
  26 Converts the mono documentation XML within a directory structure into a set
  27 of files for use with \fBmonodoc\fR(1).
  28 .TP
  29 .I mdoc export-html
  30 Converts the mono documentation XML within a directory structure into a set
  31 of HTML files that can be viewed with a web browser.
  32 .PP
  33 All of these tools (and more) use the common XML schema described in this man
  34 page.
  35 .SH FILE/DIRECTORY STRUCTURE
  36 There are three sets of Mono documentation XML files:
  37 .TP
  38 .B *
  39 .B index.xml:
  40 contains a list of all assemblies within the containing directory, and all
  41 types and namespaces within those assemblies.
  42 .TP
  43 .B *
  44 .B ns\-*.xml:
  45 There is one ns-*.xml file for each namespace within the assembly; these
  46 files are siblings to
  47 .I index.xml
  48 \&.
  49 .Sp
  50 Examples of
  51 .I ns\-*.xml
  52 files include: \fIns-System.xml\fR, \fIns-System.Collections.xml\fR, and
  53 \fIns-.xml\fR (for the root namespace, though it is recommended to NOT place
  54 types into the root namespace, as \fBmonodoc\fR(1) doesn't display them).
  55 .Sp
  56 The
  57 .I ns\-*.xml
  58 files contain per-namespace documentation.
  59 .TP
  60 .B *
  61 .B NamespaceName/TypeName.xml:
  62 These files are within a dotted
  63 .I NamespaceName
  64 directory, and
  65 .I TypeName
  66 is the name of the type.
  67 .Sp
  68 Examples include:
  69 .I RootType.xml
  70 (if the type has no namespace),
  71 \fISystem/String.xml\fR,
  72 \fISystem.Collections/IEnumerable.xml\fR, and
  73 \fISystem.Collections.Generic/List`1+Enumerator.xml\fR
  74 (the
  75 .I `1
  76 is the number of generic type parameters the type accepts, and everything
  77 after the
  78 .I +
  79 is a nested type).
  80 .PP
  81 Thus, typical directory contents would resemble:
  82
  83 .nf
  84     index.xml
  85     ns-System.xml
  86     ns-System.Collections.Generic.xml
  87     System/String.xml
  88     System.Collections.Generic/List`1.xml
  89 .fi
  90 .SH DOCUMENTATION FORMAT
  91 .SS "\fBindex.xml File Format\fR"
  92 .PP
  93 The
  94 .I index.xml
  95 file contains a list of the assemblies nested under the directory containing
  96 .I index.xml
  97 and all namespaces and types within those assemblies.  It looks something like
  98 this:
  99
 100 .nf
 101     <Overview>
 102       <Assemblies>
 103         <Assembly Name="mscorlib" Version="2.0.0.0" />
 104         <!-- other <Assembly/> elements... -->
 105       </Assemblies>
 106       <Remarks>To be added.</Remarks>
 107       <Copyright>To be added.</Copyright>
 108       <Types>
 109         <Namespace Name="System">
 110           <Type Name="String" />
 111           <!-- Other <Type/> elements -->
 112         </Namespace>
 113         <Namespace Name="System.Collections.Generic">
 114           <Type Name="List`1" DisplayName="List&lt;T&gt;" />
 115           <!-- Other <Type/> elements -->
 116         </Namespace>
 117         <!-- other <Namespace/> elements -->
 118       </Types>
 119       <Title>DocTest</Title>
 120     </Overview>
 121 .fi
 122
 123 Most of this is maintained automatically, in particular the
 124 .I /Overview/Assemblies
 125 and
 126 .I /Overview/Types
 127 elements.
 128 .PP
 129 The
 130 .I //Namespace/@Name
 131 attribute corresponds to a directory which contains files named
 132 \fI//Type/@Name\fR.xml, while the \fI//Type/@DisplayName\fR attribute contains
 133 a C# type name (if \fI//Type/@DisplayName\fR isn't found, then
 134 \fI//Type/@Name\fR is used as the display name).  There should also be a
 135 \fIns-[//Namespace/@Name].xml\fR file.
 136 .PP
 137 There are three elements of interest to authors:
 138 \fI/Overview/Remarks\fR, \fI/Overview/Copyright\fR, and
 139 \fI/Overview/Title\fR, which contain assembly-level documentation.
 140 These elements can contain any of the following XML elements (documented in
 141 the \fBDocumentation XML Elements\fR section):
 142 \fIblock\fR,
 143 \fIcode\fR,
 144 \fIexample\fR,
 145 \fIlist\fR,
 146 \fIpara\fR,
 147 \fIparamref\fR,
 148 \fItypeparamref\fR,
 149 \fIsee\fR, and
 150 \fIul\fR.
 151 .SS "\fBns-*.xml File Format\fR"
 152 The \fIns-*.xml\fR files contain namespace documentation:
 153
 154 .nf
 155     <Namespace Name="System">
 156       <Docs>
 157         <summary>To be added.</summary>
 158         <remarks>To be added.</remarks>
 159       </Docs>
 160     </Namespace>
 161 .fi
 162
 163 The \fI/Namespace/Docs/summary\fR and \fI/Namespace/Docs/remarks\fR elements
 164 should contain namespace documentation.
 165 .PP
 166 The \fIremarks\fR and \fIsummary\fR elements are documented in the
 167 \fBDocumentation XML Elements\fR section.
 168 .SS "\fBNamespaceName/TypeName.xml File Format\fR"
 169 The
 170 .I mono documentation format
 171 is similar to the Ecma documentation format, as described
 172 in ECMA-335 3rd Edition, Partition IV, Chapter 7.
 173 The principal difference from the ECMA format is that each type gets its own
 174 file, within a directory identical to the namespace of the type.  There is a
 175 lot of information that is maintained automatically by \fBmdoc\fR(1);
 176 Most of the information within the documentation should
 177 .I not
 178 be edited.  This includes the type name (\fI/Type/@FullName\fR), implemented
 179 interfaces (\fI/Type/Interfaces\fR), member information
 180 (\fI/Type/Members/Member/@MemberName\fR,
 181 \fI/Type/Members/Member/MemberSignature\fR,
 182 \fI/Type/Members/Member/MemberType\fR,
 183 \fI/Type/Members/Member/Parameters\fR, etc.).
 184
 185 .nf
 186     <Type Name="DocAttribute" FullName="Mono.DocTest.DocAttribute">
 187       <TypeSignature Language="C#" Value="public class DocAttribute : Attribute" />
 188       <AssemblyInfo>
 189         <AssemblyName>DocTest</AssemblyName>
 190         <AssemblyVersion>0.0.0.0</AssemblyVersion>
 191       </AssemblyInfo>
 192       <Base>
 193         <BaseTypeName>System.Attribute</BaseTypeName>
 194       </Base>
 195       <Interfaces />
 196       <Attributes>
 197         <Attribute>
 198           <AttributeName>System.AttributeUsage(System.AttributeTargets.All)</AttributeName>
 199         </Attribute>
 200       </Attributes>
 201       <Docs>
 202         <summary>To be added.</summary>
 203         <remarks>To be added.</remarks>
 204       </Docs>
 205       <Members>
 206         <Member MemberName=".ctor">
 207           <MemberSignature Language="C#" Value="public DocAttribute (string docs);" />
 208           <MemberType>Constructor</MemberType>
 209           <AssemblyInfo>
 210             <AssemblyVersion>0.0.0.0</AssemblyVersion>
 211           </AssemblyInfo>
 212           <Parameters>
 213             <Parameter Name="docs" Type="System.String" />
 214           </Parameters>
 215           <Docs>
 216             <param name="docs">To be added.</param>
 217             <summary>To be added.</summary>
 218             <remarks>To be added.</remarks>
 219           </Docs>
 220         </Member>
 221       </Members>
 222     </Type>
 223 .fi
 224
 225 The only elements that normally need to be edited are children of the
 226 \fI//Docs\fR elements, which usually contain the text
 227 .I To be added.
 228 The \fI/Type/Docs\fR element contains type-level documentation, while the
 229 \fI/Type/Members/Member/Docs\fR element contains per-member documentation.
 230 .PP
 231 The \fI//Docs\fR elements can contain the following elements:
 232 \fIaltcompliant\fR,
 233 \fIaltmember\fR,
 234 \fIexample\fR,
 235 \fIexception\fR,
 236 \fIparam\fR,
 237 \fIpermission\fR,
 238 \fIremarks\fR,
 239 \fIreturns\fR,
 240 \fIsince\fR,
 241 \fIsummary\fR,
 242 \fIthreadsafe\fR,
 243 \fItypeparam\fR, and
 244 \fIvalue\fR.
 245 .PP
 246 Nested types are not members; they are types, and are documented in their own
 247 file.  Consequently, the \fINamespaceName/TypeName.xml\fR files are not
 248 recursive; you do not store a \fI<Type/>\fR element within a \fI<Type/>\fR
 249 element.
 250 .SS "\fBDocumentation XML Elements\fR"
 251 The contents of the \fIDocs\fR element is \fIidentical\fR
 252 in semantics and structure to the inline C# documentation format, consisting
 253 of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2).  The
 254 following are used within the element descriptions:
 255 .TP
 256 .I CREF
 257 Refers to a class (or member) reference, and is a string in the format
 258 described below in the \fBCREF FORMAT\fR section.
 259 .TP
 260 .I TEXT
 261 Non-XML text, and XML should not be nested.
 262 .I
 263 .TP
 264 .I XML
 265 Only XML elements should be nested (which indirectly may contain text), but
 266 non-whitespace text should not be an immediate child node.
 267 .TP
 268 .I XML_TEXT
 269 Free-form text and XML, so that other XML elements may be nested.
 270 .PP
 271 The following elements are used in documentation:
 272 .TP
 273 .I <altmember cref="CREF" />
 274 .I <altmember/>
 275 is a top-level element, and should be nested directly under the
 276 .I <Docs/>
 277 element.
 278 .Sp
 279 Allows an entry to be generated for the \fISee Also\fR section.  Use
 280 \fI<see/>\fR to specify a link from within text.
 281
 282 .nf
 283     <altmember cref="P:System.Exception.Message" />
 284 .fi
 285 .TP
 286 .I <block subset="SUBSET" type="TYPE">XML_TEXT</block>
 287 Create a block of text, similar in concept to a paragraph, but is used to
 288 create divisions within the text.  To some extent, a <block/> is equivalent to
 289 the HTML <h2/> tag.
 290 .Sp
 291 .I SUBSET
 292 should always be the value \fI"none"\fR.
 293 .Sp
 294 .I TYPE
 295 specifies the heading and formatting to use.  Recognized types are:
 296 .Sp
 297 .I behaviors
 298 Creates a section with the heading \fIOperation\fR.
 299 .Sp
 300 .I note
 301 Creates a section with the heading \fINote:\fR.
 302 .Sp
 303 .I overrides
 304 Creates a section with the heading \fINote to Inheritors\fR.
 305 .Sp
 306 .I usage
 307 Creates a section with the heading \fIUsage\fR.
 308 .Sp
 309 The \fIblock\fR element can contain the following elements:
 310 \fIblock\fR,
 311 \fIc\fR,
 312 \fIcode\fR,
 313 \fIlist\fR,
 314 \fIpara\fR,
 315 \fIparamref\fR,
 316 \fIsee\fR,
 317 \fIsubscript\fR,
 318 \fIsup\fR, and
 319 \fItypeparamref\fR.
 320 .TP
 321 .I <c>XML_TEXT</c>
 322 Set text in a code-like font (similar to the HTML <tt/> element).
 323 .Sp
 324 The \fIc\fR element can contain the following elements:
 325 \fIcode\fR,
 326 \fIpara\fR,
 327 \fIparamref\fR,
 328 \fIsee\fR, and
 329 \fItypeparamref\fR.
 330 .TP
 331 .I <code lang="LANGUAGE" src="SOURCE">TEXT</code>
 332 Display multiple lines of text in a code-like font (similar to the HTML <pre/>
 333 element).
 334 .Sp
 335 .I LANGUAGE
 336 is the language this code block is for.  For example, if \fILANGUAGE\fR is
 337 \fBC#\fR, then \fITEXT\fR will get syntax highlighting for the C# language
 338 within the Mono Documentation Browser.
 339 .Sp
 340 .I SOURCE
 341 is only interpreted by \fBmdoc-update\fR(1).  If the \fIsrc\fR attribute is
 342 present when \fBmdoc-update\fR(1) is run, then \fISOURCE\fR is a file
 343 (relative to \fBmdoc-update\fR(1)'s \fB--out\fR directory) that
 344 should be inserted as the value for \fITEXT\fR.
 345 The contents of \fITEXT\fR will be ignored by \fBmdoc-update\fR(1)
 346 and replaced on every invocation.  \fISOURCE\fR can also contain an "anchor",
 347 e.g. \fIsrc="path/to/file.cs#RegionMarker"\fR.  If an anchor is present,
 348 \fIand\fR \fILANGUAGE\fR is \fIC#\fR, then \fI#region RegionMarker\fR will be
 349 searched for, and the contents between the \fI#region\fR and the following
 350 \fI#endregion\fR will be inserted as the value for \fITEXT\fR element.
 351 .TP
 352 .I <example>XML_TEXT</example>
 353 Indicates an example that should be displayed specially.  For example:
 354
 355 .nf
 356     <example>
 357       <para>An introductory paragraph.</para>
 358       <code lang="C#">
 359         class Example {
 360           public static void Main ()
 361           {
 362             System.Console.WriteLine ("Hello, World!");
 363           }
 364         }
 365       </code>
 366     </example>
 367 .fi
 368
 369 The \fIexample\fR element can contain the following elements:
 370 \fIc\fR,
 371 \fIcode\fR,
 372 \fIlist\fR,
 373 \fIpara\fR, and
 374 \fIsee\fR.
 375 .TP
 376 .I <exception cref="CREF">XML_TEXT</exception>
 377 Identifies an exception that can be thrown by the documented member.
 378 .Sp
 379 .I <exception/>
 380 is a top-level element, and should be nested directly under the
 381 .I <Docs/>
 382 element.
 383 .Sp
 384 .I CREF
 385 is the exception type that is thrown, while
 386 .I XML_TEXT
 387 contains the circumstances that would cause
 388 .I CREF
 389 to be thrown.
 390
 391 .nf
 392     <exception cref="T:System.ArgumentNullException">
 393       <paramref name="foo" /> was <see langword="null" />.
 394     </exception>
 395 .fi
 396
 397 The \fIexception\fR element can contain the following elements:
 398 \fIblock\fR,
 399 \fIpara\fR,
 400 \fIparamref\fR,
 401 \fIsee\fR, and
 402 \fItypeparamref\fR.
 403 .TP
 404 .I <format type="TYPE">XML_TEXT</format>
 405 The \fI<format/>\fR element is an "escape hatch," for including (possibly XML)
 406 content that is not valid \fBmdoc\fR(5) content.  It's the moral equivalent of
 407 \fBperlpod\fR(1) \fI=begin format\fR blocks.
 408
 409 \fITYPE\fR is the mime type of \fIXML_TEXT\fR.  \fBmdoc\fR(5) processors may
 410 skip \fIformat/>\fR blocks of they use a type that isn't supported.
 411
 412 For example:
 413
 414 .nf
 415     <format type="text/html">
 416       <table width="100%">
 417         <tr><td style="color:red">Hello, world!</td></tr>
 418       </table>
 419     </format>
 420 .fi
 421
 422 would cause the embedded HTML \fI<table/>\fR element to be inserted inline
 423 into the resulting HTML document when \fBmdoc-export-html\fR(1) processes the
 424 file.  (Likewise, it may be skipped if processed by another program.)
 425
 426 \fIformat/>\fR is intended to simplify importing documentation from existing
 427 documentation sources.  It should not be relied upon, if at all possible.
 428 .TP
 429 .I <list>XML</list>
 430 Create a list or table of items.
 431 .I <list/>
 432 makes use of nested \fI<item>XML</item>\fR, \fI<listheader>XML</listheader>\fR,
 433 \fI<term>XML_TEXT</term>\fR, and \fI<description>XML_TEXT</description>\fR
 434 elements.
 435 .Sp
 436 \fILists\fR have the syntax:
 437
 438 .nf
 439     <list type="bullet"> <!-- or type="number" -->
 440       <item><term>Bullet 1</term></item>
 441       <item><term>Bullet 2</term></item>
 442       <item><term>Bullet 3</term></item>
 443     </list>
 444 .fi
 445 .Sp
 446 .I Tables
 447 have the syntax:
 448
 449 .nf
 450     <list type="table">
 451       <listheader> <!-- listheader bolds this row -->
 452         <term>Column 1</term>
 453         <description>Column 2</description>
 454         <description>Column 3</description>
 455       </listheader>
 456       <item>
 457         <term>Item 1-A</term>
 458         <description>Item 1-B</description>
 459         <description>Item 1-C</description>
 460       </item>
 461       <item>
 462         <term>Item 2-A</term>
 463         <description>Item 2-B</description>
 464         <description>Item 2-C</description>
 465       </item>
 466     </list>
 467 .fi
 468
 469 The \fIitem\fR and \fIdescription\fR elements can each contain text and
 470 the following elements:
 471 \fIblock\fR,
 472 \fIc\fR,
 473 \fIpara\fR,
 474 \fIparamref\fR,
 475 \fIsee\fR,
 476 \fIsup\fR, and
 477 \fItypeparamref\fR.
 478 .TP
 479 .I <para>XML_TEXT</para>
 480 Insert a paragraph of \fIXML_TEXT\fR.
 481 For example,
 482
 483 .nf
 484     <para>
 485       This is a paragraph of text.
 486     </para>
 487 .fi
 488
 489 The \fIpara\fR element can contain the following elements:
 490 \fIblock\fR,
 491 \fIc\fR,
 492 \fIexample\fR,
 493 \fIlink\fR,
 494 \fIlist\fR,
 495 \fIonequarter\fR,
 496 \fIparamref\fR,
 497 \fIsee\fR,
 498 \fIsub\fR,
 499 \fIsup\fR,
 500 \fItypeparamref\fR, and
 501 \fIul\fR.
 502 .TP
 503 .I <param name="NAME">XML_TEXT</param>
 504 .I <param/>
 505 is a top-level element, and should be nested directly under the
 506 .I <Docs/>
 507 element.
 508 .Sp
 509 Describes the parameter \fINAME\fR of the current constructor, method, or
 510 property:
 511
 512 .nf
 513     <param name="count">
 514       A <see cref="T:System.Int32" /> containing the number
 515       of widgets to process.
 516     </param>
 517 .fi
 518
 519
 520 The \fIparam\fR element can contain the following elements:
 521 \fIblock\fR,
 522 \fIc\fR,
 523 \fIexample\fR,
 524 \fIpara\fR,
 525 \fIparamref\fR,
 526 \fIsee\fR, and
 527 \fItypeparamref\fR.
 528 .TP
 529 .I <paramref name="NAME" />
 530 Indicates that \fINAME\fR is a parameter.
 531 .Sp
 532 This usually renders \fINAME\fR as italic text, so it is frequently
 533 (ab)used as an equivalent to the HTML <i/> element.  See the
 534 \fI<exception/>\fR documentation (above) for an example.
 535 .Sp
 536 .TP
 537 .I <permission cref="CREF">XML_TEXT</permission>
 538 Documents the security accessibility requirements of the current member.
 539 .Sp
 540 .I <permission/>
 541 is a top-level element, and should be nested directly under the
 542 .I <Docs/>
 543 element.
 544 .Sp
 545 \fICREF\fR is a type reference to the security permission required, while
 546 \fIXML_TEXT\fR is a description of why the permission is required.
 547
 548 .nf
 549     <permission cref="T:System.Security.Permissions.FileIOPermission">
 550       Requires permission for reading and writing files. See
 551       <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
 552       <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
 553     </permission>
 554 .fi
 555
 556 The \fIpermission\fR element can contain the following elements:
 557 \fIblock\fR,
 558 \fIpara\fR,
 559 \fIparamref\fR,
 560 \fIsee\fR, and
 561 \fItypeparamref\fR.
 562 .TP
 563 .I <remarks>XML_TEXT</remarks>
 564 Contains detailed information about a member.
 565 .Sp
 566 .I <remarks/>
 567 is a top-level element, and should be nested directly under the
 568 .I <Docs/>
 569 element.
 570
 571 .nf
 572     <remarks>
 573       Insert detailed information here.
 574     </remarks>
 575 .fi
 576
 577 The \fIremarks\fR element can contain the following elements:
 578 \fIblock\fR,
 579 \fIc\fR,
 580 \fIcode\fR,
 581 \fIexample\fR,
 582 \fIlist\fR,
 583 \fIpara\fR,
 584 \fIparamref\fR,
 585 \fIsee\fR, and
 586 \fItypeparamref\fR.
 587 .TP
 588 .I <returns>XML_TEXT</returns>
 589 .Sp
 590 .I <returns/>
 591 is a top-level element, and should be nested directly under the
 592 .I <Docs/>
 593 element.
 594 .Sp
 595 Describes the return value of a method:
 596
 597 .nf
 598     <returns>
 599       A <see cref="T:System.Boolean" /> specifying whether
 600       or not the process can access
 601       <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
 602     </returns>
 603 .fi
 604
 605 The \fIreturns\fR element can contain the following elements:
 606 \fIc\fR,
 607 \fIformat\fR,
 608 \fIlist\fR,
 609 \fIpara\fR,
 610 \fIparamref\fR,
 611 \fIsee\fR, and
 612 \fItypeparamref\fR.
 613 .TP
 614 \fI<see cref="CREF" />\fR, \fI<see langword="LANGWORD" />\fR
 615 Creates a link to the specified member within the current text:
 616
 617 .nf
 618     <see cref="M:Some.Namespace.With.Type.Method" />
 619 .fi
 620
 621 or specifies that \fILANGWORD\fR is a language keyword:
 622
 623 .nf
 624     <see langword="null" />
 625 .fi
 626
 627 .TP
 628 .I <seealso cref="CREF" />
 629 Do not use \fIseealso\fR, use \fIaltmember\fR.
 630 .TP
 631 .I <since version="VERSION" />
 632 .Sp
 633 .I <since/>
 634 is a top-level element, and should be nested directly under the
 635 \fI<Docs/>\fR element.
 636 .Sp
 637 Permits specification of which version introduced the specified type or
 638 member.
 639
 640 .nf
 641     <since version="Gtk# 2.4" />
 642 .fi
 643
 644 This generally isn't required, as the \fI//AssemblyInfo/AssemblyVersion\fR
 645 elements track which assembly versions contain type or member.
 646 .TP
 647 .I <summary>XML_TEXT</summary>
 648 .Sp
 649 .I <summary/>
 650 is a top-level element, and should be nested directly under the
 651 .I <Docs/>
 652 element.
 653 .Sp
 654 Provides a (brief!) overview about a type or type member.
 655 .Sp
 656 This is usually displayed as part of a class declaration, and should be a
 657 reasonably short description of the type/member.  Use
 658 .I <remarks/>
 659 for more detailed information.
 660 .Sp
 661 The \fIsummary\fR element can contain the following elements:
 662 \fIblock\fR,
 663 \fIlist\fR,
 664 \fIpara\fR,
 665 \fIparamref\fR,
 666 \fIsee\fR, and
 667 \fItypeparamref\fR.
 668 .TP
 669 .I <typeparam name="NAME">XML_TEXT</typeparam>
 670 .I <typeparam/>
 671 is a top-level element, and should be nested directly under the
 672 .I <Docs/>
 673 element.
 674 .Sp
 675 This is used to document a type parameter for a generic type or generic method.
 676 .Sp
 677 .I NAME
 678 is the name of the type parameter, while
 679 .I XML_TEXT
 680 contains a description of the parameter (what it's used for, what restrictions
 681 it must meet, etc.).
 682
 683 .nf
 684     <typeparam name="T">
 685       The type of the underlying collection
 686     </typeparam>
 687 .fi
 688
 689 The \fItypeparam\fR element can contain the following elements:
 690 \fIblock\fR,
 691 \fIc\fR,
 692 \fIpara\fR,
 693 \fIparamref\fR,
 694 \fIsee\fR, and
 695 \fItypeparamref\fR.
 696 .TP
 697 .I <typeparamref name="NAME">
 698 Used to indicate that \fINAME\fR is a type parameter.
 699 .TP
 700 .I <value>XML_TEXT</value>
 701 .I <value/>
 702 is a top-level element, and should be nested directly under the
 703 .I <Docs/>
 704 element.
 705 .Sp
 706 Allows a property to be described.
 707
 708 .nf
 709     <value>
 710       A <see cref="T:System.String" /> containing a widget name.
 711     </value>
 712 .fi
 713
 714 The \fIvalue\fR element can contain the following elements:
 715 \fIblock\fR,
 716 \fIc\fR,
 717 \fIexample\fR,
 718 \fIlist\fR,
 719 \fIpara\fR,
 720 \fIparamref\fR,
 721 \fIsee\fR, and
 722 \fItypeparamref\fR.
 723 .PP
 724 .SH CREF FORMAT
 725 String IDs (\fICREF\fRs) are used to refer to a type or member of a type.
 726 String IDs are documented in ECMA-334 3rd Edition, Annex E.3.1.  They consist
 727 of a \fImember type prefix\fR, the full type name (namespace + name, separated
 728 by \fI.\fR), possibly followed by the member name and other information.
 729 .PP
 730 Member type prefixes:
 731 .TP
 732 .I "C:"
 733 The CREF refers to a constructor.  The (optional) parameter list is
 734 enclosed in parenthesis and follows the type name:
 735 \fIC:System.String(System.Char,System.Int32)\fR.
 736 .TP
 737 .I "E:"
 738 The CREF refers to an event.  The event name follows the type name:
 739 \fIE:System.AppDomain.AssemblyLoad\fR.
 740 .TP
 741 .I "F:"
 742 The CREF refers to a field.  The field name follows the type name:
 743 \fIF:System.Runtime.InteropServices.DllImportAttribute.SetLastError\fR.
 744 .TP
 745 .I "M:"
 746 Refers to a constructor or method.  Constructors may append
 747 .I .ctor
 748 to the type name (instead of using the above
 749 .I C:
 750 constructor format), while methods append the method name and an (optional)
 751 count of the number of generic parameters.  Both constructors and methods
 752 may append the method parameter list enclosed in parenthesis.
 753 .Sp
 754 Examples:
 755 \fIM:System.Object..ctor\fR,
 756 \fIM:System.String..ctor(System.Char[])\fR,
 757 \fIM:System.String.Concat(System.Object)\fR,
 758 \fIM:System.Array.Sort``1(``0[])\fR,
 759 \fIM:System.Collections.Generic.List`1..ctor\fR,
 760 \fIM:System.Collections.Generic.List`1.Add(`0)\fR.
 761 .TP
 762 .I "N:"
 763 Refers to a namespace, e.g. \fIN:System\fR.
 764 .TP
 765 .I "P:"
 766 Refers to a property.  If the property is an indexer or takes parameters,
 767 the parameter types are appended to the property name and enclosed with
 768 parenthesis:
 769 \fIP:System.String.Length\fR,
 770 \fIP:System.String.Chars(System.Int32)\fR.
 771 .TP
 772 .I "T:"
 773 The CREF refers to a type, with the number of generic types appended:
 774 \fIT:System.String\fR,
 775 \fIT:System.Collections.Generic.List`1\fR,
 776 \fIT:System.Collections.Generic.List`1.Enumerator\fR.
 777 .PP
 778 To make matters more interesting, generic types & members have two
 779 representations: the "unbound" representation (shown in examples above), in
 780 which class names have the count of generic parameters appended to their name.
 781 There is also a "bound" representation, in which the binding of generic
 782 parameters is listed within '{' and '}' or '<' and '>'.
 783 (Use of '<' and '>' is less common, as within an XML document their escaped
 784 character entities must instead be used, leading to '&lt;' and '&gt;'.)
 785 .PP
 786 .B Unbound:
 787 .TP
 788 .B *
 789 .I T:System.Collections.Generic.List`1
 790 .TP
 791 .B *
 792 .I T:System.Collections.Generic.Dictionary`2
 793 .PP
 794 .B Bound:
 795 .TP
 796 .B *
 797 .I T:System.Collections.Generic.List{System.Int32}
 798 .TP
 799 .B *
 800 .I T:System.Collections.Generic.List<System.Int32>
 801 .TP
 802 .B *
 803 .I T:System.Collections.Generic.List&lt;System.Int32&gt;
 804 .TP
 805 .B *
 806 .I T:System.Predicate{System.Action{System.String}}
 807 .PP
 808 As you can see, bound variants can be arbitrarily complex (just like
 809 generics).
 810 .PP
 811 Furthermore, if a generic parameter is bound to the generic parameter of a
 812 type or method, the "index" of the type/method's generic parameter is used
 813 as the binding, so given
 814
 815 .nf
 816     class FooType {
 817       public static void Foo<T> (System.Predicate<T> predicate)
 818       {
 819       }
 820     }
 821 .fi
 822
 823 The CREF for this method is
 824 \fIM:FooType.Foo``1(System.Predicate{``0})\fR,
 825 .I ``0
 826 is the 0th generic parameter index which is bound to
 827 \fISystem.Predicate<T>\fR.
 828 .SH SEE ALSO
 829 mdoc(1), monodocer(1)
 830 .SH MAILING LISTS
 831 .TP
 832 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 833 .SH WEB SITE
 834 Visit http://www.mono-project.com for details