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 <list>XML</list>
 405 Create a list or table of items.
 406 .I <list/>
 407 makes use of nested \fI<item>XML</item>\fR, \fI<listheader>XML</listheader>\fR,
 408 \fI<term>XML_TEXT</term>\fR, and \fI<description>XML_TEXT</description>\fR
 409 elements.
 410 .Sp
 411 \fILists\fR have the syntax:
 412
 413 .nf
 414     <list type="bullet"> <!-- or type="number" -->
 415       <item><term>Bullet 1</term></item>
 416       <item><term>Bullet 2</term></item>
 417       <item><term>Bullet 3</term></item>
 418     </list>
 419 .fi
 420 .Sp
 421 .I Tables
 422 have the syntax:
 423
 424 .nf
 425     <list type="table">
 426       <listheader> <!-- listheader bolds this row -->
 427         <term>Column 1</term>
 428         <description>Column 2</description>
 429         <description>Column 3</description>
 430       </listheader>
 431       <item>
 432         <term>Item 1-A</term>
 433         <description>Item 1-B</description>
 434         <description>Item 1-C</description>
 435       </item>
 436       <item>
 437         <term>Item 2-A</term>
 438         <description>Item 2-B</description>
 439         <description>Item 2-C</description>
 440       </item>
 441     </list>
 442 .fi
 443
 444 The \fIitem\fR and \fIdescription\fR elements can each contain text and
 445 the following elements:
 446 \fIblock\fR,
 447 \fIc\fR,
 448 \fIpara\fR,
 449 \fIparamref\fR,
 450 \fIsee\fR,
 451 \fIsup\fR, and
 452 \fItypeparamref\fR.
 453 .TP
 454 .I <para>XML_TEXT</para>
 455 Insert a paragraph of \fIXML_TEXT\fR.
 456 For example,
 457
 458 .nf
 459     <para>
 460       This is a paragraph of text.
 461     </para>
 462 .fi
 463
 464 The \fIpara\fR element can contain the following elements:
 465 \fIblock\fR,
 466 \fIc\fR,
 467 \fIexample\fR,
 468 \fIlink\fR,
 469 \fIlist\fR,
 470 \fIonequarter\fR,
 471 \fIparamref\fR,
 472 \fIsee\fR,
 473 \fIsub\fR,
 474 \fIsup\fR,
 475 \fItypeparamref\fR, and
 476 \fIul\fR.
 477 .TP
 478 .I <param name="NAME">XML_TEXT</param>
 479 .I <param/>
 480 is a top-level element, and should be nested directly under the
 481 .I <Docs/>
 482 element.
 483 .Sp
 484 Describes the parameter \fINAME\fR of the current constructor, method, or
 485 property:
 486
 487 .nf
 488     <param name="count">
 489       A <see cref="T:System.Int32" /> containing the number
 490       of widgets to process.
 491     </param>
 492 .fi
 493
 494
 495 The \fIparam\fR element can contain the following elements:
 496 \fIblock\fR,
 497 \fIc\fR,
 498 \fIexample\fR,
 499 \fIpara\fR,
 500 \fIparamref\fR,
 501 \fIsee\fR, and
 502 \fItypeparamref\fR.
 503 .TP
 504 .I <paramref name="NAME" />
 505 Indicates that \fINAME\fR is a parameter.
 506 .Sp
 507 This usually renders \fINAME\fR as italic text, so it is frequently
 508 (ab)used as an equivalent to the HTML <i/> element.  See the
 509 \fI<exception/>\fR documentation (above) for an example.
 510 .Sp
 511 .TP
 512 .I <permission cref="CREF">XML_TEXT</permission>
 513 Documents the security accessibility requirements of the current member.
 514 .Sp
 515 .I <permission/>
 516 is a top-level element, and should be nested directly under the
 517 .I <Docs/>
 518 element.
 519 .Sp
 520 \fICREF\fR is a type reference to the security permission required, while
 521 \fIXML_TEXT\fR is a description of why the permission is required.
 522
 523 .nf
 524     <permission cref="T:System.Security.Permissions.FileIOPermission">
 525       Requires permission for reading and writing files. See
 526       <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
 527       <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
 528     </permission>
 529 .fi
 530
 531 The \fIpermission\fR element can contain the following elements:
 532 \fIblock\fR,
 533 \fIpara\fR,
 534 \fIparamref\fR,
 535 \fIsee\fR, and
 536 \fItypeparamref\fR.
 537 .TP
 538 .I <remarks>XML_TEXT</remarks>
 539 Contains detailed information about a member.
 540 .Sp
 541 .I <remarks/>
 542 is a top-level element, and should be nested directly under the
 543 .I <Docs/>
 544 element.
 545
 546 .nf
 547     <remarks>
 548       Insert detailed information here.
 549     </remarks>
 550 .fi
 551
 552 The \fIremarks\fR element can contain the following elements:
 553 \fIblock\fR,
 554 \fIc\fR,
 555 \fIcode\fR,
 556 \fIexample\fR,
 557 \fIlist\fR,
 558 \fIpara\fR,
 559 \fIparamref\fR,
 560 \fIsee\fR, and
 561 \fItypeparamref\fR.
 562 .TP
 563 .I <returns>XML_TEXT</returns>
 564 .Sp
 565 .I <returns/>
 566 is a top-level element, and should be nested directly under the
 567 .I <Docs/>
 568 element.
 569 .Sp
 570 Describes the return value of a method:
 571
 572 .nf
 573     <returns>
 574       A <see cref="T:System.Boolean" /> specifying whether
 575       or not the process can access
 576       <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
 577     </returns>
 578 .fi
 579
 580 The \fIreturns\fR element can contain the following elements:
 581 \fIlist\fR,
 582 \fIpara\fR,
 583 \fIparamref\fR,
 584 \fIsee\fR, and
 585 \fItypeparamref\fR.
 586 .TP
 587 \fI<see cref="CREF" />\fR, \fI<see langword="LANGWORD" />\fR
 588 Creates a link to the specified member within the current text:
 589
 590 .nf
 591     <see cref="M:Some.Namespace.With.Type.Method" />
 592 .fi
 593
 594 or specifies that \fILANGWORD\fR is a language keyword:
 595
 596 .nf
 597     <see langword="null" />
 598 .fi
 599
 600 .TP
 601 .I <seealso cref="CREF" />
 602 Do not use \fIseealso\fR, use \fIaltmember\fR.
 603 .TP
 604 .I <since version="VERSION" />
 605 .Sp
 606 .I <since/>
 607 is a top-level element, and should be nested directly under the
 608 \fI<Docs/>\fR element.
 609 .Sp
 610 Permits specification of which version introduced the specified type or
 611 member.
 612
 613 .nf
 614     <since version="Gtk# 2.4" />
 615 .fi
 616
 617 This generally isn't required, as the \fI//AssemblyInfo/AssemblyVersion\fR
 618 elements track which assembly versions contain type or member.
 619 .TP
 620 .I <summary>XML_TEXT</summary>
 621 .Sp
 622 .I <summary/>
 623 is a top-level element, and should be nested directly under the
 624 .I <Docs/>
 625 element.
 626 .Sp
 627 Provides a (brief!) overview about a type or type member.
 628 .Sp
 629 This is usually displayed as part of a class declaration, and should be a
 630 reasonably short description of the type/member.  Use
 631 .I <remarks/>
 632 for more detailed information.
 633 .Sp
 634 The \fIsummary\fR element can contain the following elements:
 635 \fIblock\fR,
 636 \fIlist\fR,
 637 \fIpara\fR,
 638 \fIparamref\fR,
 639 \fIsee\fR, and
 640 \fItypeparamref\fR.
 641 .TP
 642 .I <typeparam name="NAME">XML_TEXT</typeparam>
 643 .I <typeparam/>
 644 is a top-level element, and should be nested directly under the
 645 .I <Docs/>
 646 element.
 647 .Sp
 648 This is used to document a type parameter for a generic type or generic method.
 649 .Sp
 650 .I NAME
 651 is the name of the type parameter, while
 652 .I XML_TEXT
 653 contains a description of the parameter (what it's used for, what restrictions
 654 it must meet, etc.).
 655
 656 .nf
 657     <typeparam name="T">
 658       The type of the underlying collection
 659     </typeparam>
 660 .fi
 661
 662 The \fItypeparam\fR element can contain the following elements:
 663 \fIblock\fR,
 664 \fIc\fR,
 665 \fIpara\fR,
 666 \fIparamref\fR,
 667 \fIsee\fR, and
 668 \fItypeparamref\fR.
 669 .TP
 670 .I <typeparamref name="NAME">
 671 Used to indicate that \fINAME\fR is a type parameter.
 672 .TP
 673 .I <value>XML_TEXT</value>
 674 .I <value/>
 675 is a top-level element, and should be nested directly under the
 676 .I <Docs/>
 677 element.
 678 .Sp
 679 Allows a property to be described.
 680
 681 .nf
 682     <value>
 683       A <see cref="T:System.String" /> containing a widget name.
 684     </value>
 685 .fi
 686
 687 The \fIvalue\fR element can contain the following elements:
 688 \fIblock\fR,
 689 \fIc\fR,
 690 \fIexample\fR,
 691 \fIlist\fR,
 692 \fIpara\fR,
 693 \fIparamref\fR,
 694 \fIsee\fR, and
 695 \fItypeparamref\fR.
 696 .PP
 697 .SH CREF FORMAT
 698 String IDs (\fICREF\fRs) are used to refer to a type or member of a type.
 699 String IDs are documented in ECMA-334 3rd Edition, Annex E.3.1.  They consist
 700 of a \fImember type prefix\fR, the full type name (namespace + name, separated
 701 by \fI.\fR), possibly followed by the member name and other information.
 702 .PP
 703 Member type prefixes:
 704 .TP
 705 .I "C:"
 706 The CREF refers to a constructor.  The (optional) parameter list is
 707 enclosed in parenthesis and follows the type name:
 708 \fIC:System.String(System.Char,System.Int32)\fR.
 709 .TP
 710 .I "E:"
 711 The CREF refers to an event.  The event name follows the type name:
 712 \fIE:System.AppDomain.AssemblyLoad\fR.
 713 .TP
 714 .I "F:"
 715 The CREF refers to a field.  The field name follows the type name:
 716 \fIF:System.Runtime.InteropServices.DllImportAttribute.SetLastError\fR.
 717 .TP
 718 .I "M:"
 719 Refers to a constructor or method.  Constructors may append
 720 .I .ctor
 721 to the type name (instead of using the above
 722 .I C:
 723 constructor format), while methods append the method name and an (optional)
 724 count of the number of generic parameters.  Both constructors and methods
 725 may append the method parameter list enclosed in parenthesis.
 726 .Sp
 727 Examples:
 728 \fIM:System.Object..ctor\fR,
 729 \fIM:System.String..ctor(System.Char[])\fR,
 730 \fIM:System.String.Concat(System.Object)\fR,
 731 \fIM:System.Array.Sort``1(``0[])\fR,
 732 \fIM:System.Collections.Generic.List`1..ctor\fR,
 733 \fIM:System.Collections.Generic.List`1.Add(`0)\fR.
 734 .TP
 735 .I "N:"
 736 Refers to a namespace, e.g. \fIN:System\fR.
 737 .TP
 738 .I "P:"
 739 Refers to a property.  If the property is an indexer or takes parameters,
 740 the parameter types are appended to the property name and enclosed with
 741 paranthesis:
 742 \fIP:System.String.Length\fR,
 743 \fIP:System.String.Chars(System.Int32)\fR.
 744 .TP
 745 .I "T:"
 746 The CREF refers to a type, with the number of generic types appended:
 747 \fIT:System.String\fR,
 748 \fIT:System.Collections.Generic.List`1\fR,
 749 \fIT:System.Collections.Generic.List`1.Enumerator\fR.
 750 .PP
 751 To make matters more interesting, generic types & members have two
 752 representations: the "unbound" representation (shown in examples above), in
 753 which class names have the count of generic parameters appended to their name.
 754 There is also a "bound" representation, in which the binding of generic
 755 parameters is listed within '{' and '}' or '<' and '>'.
 756 (Use of '<' and '>' is less common, as within an XML document their escaped
 757 character entities must instead be used, leading to '&lt;' and '&gt;'.)
 758 .PP
 759 .B Unbound:
 760 .TP
 761 .B *
 762 .I T:System.Collections.Generic.List`1
 763 .TP
 764 .B *
 765 .I T:System.Collections.Generic.Dictionary`2
 766 .PP
 767 .B Bound:
 768 .TP
 769 .B *
 770 .I T:System.Collections.Generic.List{System.Int32}
 771 .TP
 772 .B *
 773 .I T:System.Collections.Generic.List<System.Int32>
 774 .TP
 775 .B *
 776 .I T:System.Collections.Generic.List&lt;System.Int32&gt;
 777 .TP
 778 .B *
 779 .I T:System.Predicate{System.Action{System.String}}
 780 .PP
 781 As you can see, bound variants can be arbitrarily complex (just like
 782 generics).
 783 .PP
 784 Furthermore, if a generic parameter is bound to the generic parameter of a
 785 type or method, the "index" of the type/method's generic parameter is used
 786 as the binding, so given
 787
 788 .nf
 789     class FooType {
 790       public static void Foo<T> (System.Predicate<T> predicate)
 791       {
 792       }
 793     }
 794 .fi
 795
 796 The CREF for this method is
 797 \fIM:FooType.Foo``1(System.Predicate{``0})\fR,
 798 .I ``0
 799 is the 0th generic parameter index which is bound to
 800 \fISystem.Predicate<T>\fR.
 801 .SH SEE ALSO
 802 mdoc(1), monodocer(1)
 803 .SH MAILING LISTS
 804 .TP
 805 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 806 .SH WEB SITE
 807 Visit http://www.mono-project.com for details