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