man/monodocer.1

   1 .\"
   2 .\" monodocer manual page.
   3 .\" (C) 2006 Jonathan Pryor
   4 .\" Author:
   5 .\"   Jonathan Pryor (jonpryor@vt.edu)
   6 .\"
   7 .de Sp \" Vertical space (when we can't use .PP)
   8 .if t .sp .5v
   9 .if n .sp
  10 ..
  11 .TH "monodocer" 1
  12 .SH NAME
  13 monodocer \- ECMA Documentation Format Support
  14 .SH SYNOPSIS
  15 .B monodocer
  16 [OPTIONS]*
  17 .SH OPTIONS
  18 .TP
  19 .I \-assembly:ASSEMBLY
  20 .I ASSEMBLY
  21 is a .NET assembly to generate documentation stubs for.
  22 .Sp
  23 Specify a file path or the name of a GAC'd assembly.
  24 .TP
  25 .I \-delete
  26 Allow monodocer to delete members from documentation files.
  27 The only members deleted are for members which are no longer present within
  28 the assembly.
  29 .Sp
  30 If a type is no longer present, the documentation file is
  31 .I not
  32 deleted, but is instead
  33 .I renamed
  34 to have a
  35 .B .remove
  36 extension.
  37 .TP
  38 .I \-?, \-help
  39 Show program argument information.
  40 .TP
  41 .I \-ignoremembers
  42 Do not update members.
  43 .Sp
  44 This will add documentation stubs for added types, but will
  45 .I not
  46 add or remove documentation for any members of any type (including any added
  47 types).
  48 .TP
  49 .I \-importslashdoc:FILE
  50 .I FILE
  51 is an XML file generated with the
  52 .B /doc:FILE
  53 C# compiler flag (e.g.
  54 .I mcs -doc:foo.xml foo.cs
  55 ).  Import the member documentation contained within
  56 .I FILE
  57 into the documentation format used by monodoc.
  58 .TP
  59 .I \-name:NAME
  60 .I NAME
  61 is the name of the project this documentation is for.
  62 .Sp
  63 This sets the
  64 .I /Overview/Title
  65 element within the
  66 .I index.xml
  67 file created at the directory specified by
  68 .I -path
  69 \&.
  70 This is used by some programs for title information (e.g.
  71 .I monodocs2html
  72 ).
  73 .TP
  74 .I \-namespace:NAMESPACE
  75 Only update the types within the namespace
  76 .I NAMESPACE
  77 \&.
  78 .TP
  79 .I \-overrides
  80 Include overridden methods in documentation.
  81 .Sp
  82 This normally isn't necessary, as the Mono Documentation Browser will provide a
  83 link to the base type members anyway, as will
  84 .I monodocs2html
  85 if the base type is within the same assembly.
  86 .TP
  87 .I \-path:OUTPUT_DIR
  88 .I OUTPUT_DIR
  89 is the directory which will contain the new/updated documentation stubs.
  90 .TP
  91 .I \-pretty
  92 Indent the XML files nicely.
  93 .TP
  94 .I \-since:SINCE
  95 Create a <since/> element for added types and members with the value
  96 .I SINCE
  97 \&.
  98 .Sp
  99 For example, when given
 100 .I -since:"Gtk# 2.4"
 101 an element will be inserted into the
 102 .I Docs
 103 element for all added types and type members:
 104 .nf
 105         <since version="Gtk# 2.4" />
 106 .fi
 107 The Mono Documentation Browser and
 108 .I monodocs2html
 109 will use this element to specify in which version a member was added.
 110 .TP
 111 .I \-type:TYPE
 112 Only create/update documentation for the type
 113 .I TYPE
 114 \&.
 115 .TP
 116 .I \-updateto:PATH
 117 When updating documentation, write the updated documentation files into the
 118 directory
 119 .I PATH
 120 \&.
 121 .TP
 122 .I \-V, \-version
 123 Display version and licensing information.
 124 .PP
 125 .SH DESCRIPTION
 126 \fBmonodocer\fR has been obsoleted by \fBmdoc\fR(1).  See the
 127 \fBmdoc-update\fR(1) man page.
 128 .PP
 129 .I monodocer
 130 is a program that creates XML documentation stubs in the ECMA Documentation
 131 Format.  It does not rely on documentation found within the source code.
 132 .PP
 133 The advantages are:
 134 .TP
 135 .I *
 136 .B Code readability.
 137 Good documentation is frequently (a) verbose, and (b)
 138 filled with examples.  (For comparison, compare Microsoft .NET Framework
 139 documentation, which is often a page or more of docs for each member, to
 140 JavaDoc documentation, which can often be a sentence for each member.)
 141 .Sp
 142 Inserting good documentation into the source code can frequently bloat the
 143 source file, as the documentation can be longer than the actual method that is
 144 being documented.
 145 .TP
 146 .I *
 147 .B Localization.
 148 In-source documentation formats (such as
 149 .B /doc
 150 ) have no support for multiple human languages.  If you need to support more
 151 than one human language for documentation purposes,
 152 .I monodocer
 153 is useful as it permits each language to get its own directory, and
 154 .I monodocer
 155 can add types/members for each separate documentation directory.
 156 .TP
 157 .I *
 158 .B Administration.
 159 It's not unusual to have separate documentation and development teams.  It's
 160 also possible that the documentation team will have minimal experience with
 161 the programming language being used.  In such circumstances, inline
 162 documentation is not desirable as the documentation team could inadvertantly
 163 insert an error into the source code while updating the documentation.
 164 Alternatively, you may not want the documentation team to have access to the
 165 source code for security reasons.
 166 .I monodocer
 167 allows the documentation to be kept
 168 .I completely
 169 separate and distinct from the source code used to create the assembly.
 170 .PP
 171 To turn the
 172 .I monodocer
 173 documentation into something that can be consumed by the Mono
 174 Documentation Browser (the desktop help browser, or the web interface
 175 for it) it is necessary to compile the documentation into a packed
 176 format.  This is done with the mdassembler tool, for example, you
 177 could use this toolchain like this:
 178 .nf
 179
 180         $ monodocer -assembly:MyWidgets -path:generated_docs
 181         $ mdassembler --ecma generated_docs -out:MyWidgets
 182
 183 .fi
 184 The above would generate a MyWidgets.zip and a MyWidgets.tree that can
 185 then be installed in the system.   In addition to the two files (.zip
 186 and .tree) you must provide a .sources file which describes where in
 187 the help system the documentation should be hooked up, it is a very
 188 simple XML file, like this:
 189 .nf
 190
 191 <?xml version="1.0"?>
 192 <monodoc>
 193   <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>
 194 </monodoc>
 195
 196 .fi
 197 The above configuration file describes that the documentation is in
 198 ECMA format (the compiled version) that the base file name is
 199 MyWidgets and that it should be hooked up in the "classlib-gnome" part
 200 of the tree.   If you want to look at the various nodes defined in the
 201 documentation, you can look at monodoc.xml file which is typically
 202 installed in /usr/lib/monodoc/monodoc.xml.
 203 .PP
 204 Once you have all of your files (.zip, .tree and .sources) you can
 205 install them into the system with the following command:
 206 .nf
 207
 208         $ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`
 209
 210 .fi
 211 The above will copy the files into the directory that Monodoc has
 212 registered (you might need root permissions to do this).   The actual
 213 directory is returned by the
 214 .I pkg-config
 215 invocation.
 216 .SH STRING ID FORMAT
 217 String IDs are used to refer to a type or member of a type.  String IDs are
 218 documented in ECMA-334 3rd Edition, Annex E.3.1.  They consist of a
 219 .I member type prefix
 220 , the full type name (namespace + name, separated by '.'), possibly followed
 221 by the member name and other information.
 222 .PP
 223 Member type prefixes:
 224 .TP
 225 .I "E:"
 226 The String ID refers to an event.  The event name follows the type name:
 227 .I E:System.AppDomain.AssemblyLoad
 228 .TP
 229 .I "F:"
 230 The String ID refers to a field.  The field name follows the type name:
 231 .I F:System.Runtime.InteropServices.DllImportAttribute.SetLastError
 232 .TP
 233 .I "M:"
 234 Refers to a constructor or method.  Constructors append
 235 .I .ctor
 236 to the type name, while methods append the method name (with an optional count
 237 of the number of generic parameters).
 238 .Sp
 239 If the constructor or method take arguments, these are listed within
 240 parenthesis after the constructor/method name:
 241 .Sp
 242 .I M:System.Object..ctor
 243 ,
 244 .I M:System.String..ctor(System.Char[])
 245 ,
 246 .I M:System.String.Concat(System.Object)
 247 ,
 248 .I M:System.Array.Sort``1(``0[])
 249 ,
 250 .I M:System.Collections.Generic.List`1..ctor
 251 ,
 252 .I M:System.Collections.Generic.List`1.Add(`0)
 253 \&.
 254 .TP
 255 .I "N:"
 256 Refers to a namespace, e.g.
 257 .I N:System
 258 .TP
 259 .I "P:"
 260 Refers to a property.  If the property is an indexer or takes parameters,
 261 the parameter types are appended to the property name and enclosed with
 262 parenthesis:
 263 .I P:System.String.Length
 264 ,
 265 .I P:System.String.Chars(System.Int32)
 266 \&.
 267 .TP
 268 .I "T:"
 269 The String ID refers to a type, with the number of generic types appended:
 270 .I T:System.String
 271 ,
 272 .I T:System.Collections.Generic.List`1
 273 .PP
 274 To make matters more interesting, generic types & members have two
 275 representations: the "unbound" representation (shown in examples above), in
 276 which class names have the count of generic parameters appended to their name.
 277 There is also a "bound" representation, in which the binding of generic
 278 parameters is listed within '{' and '}'.
 279 .PP
 280 .B Unbound:
 281 .I T:System.Collections.Generic.List`1
 282 ,
 283 .I T:System.Collections.Generic.Dictionary`2
 284 \&.
 285 .PP
 286 .B Bound:
 287 .I T:System.Collections.Generic.List{System.Int32}
 288 .I T:System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Predicate{System.String}}}
 289 \&.
 290 .PP
 291 As you can see, bound variants can be arbitrarily complex (just like
 292 generics).
 293 .PP
 294 Furthermore, if a generic parameter is bound to the generic parameter of a
 295 type or method, the "index" of the type/method's generic parameter is used
 296 as the binding, so given
 297 .nf
 298         class FooType {
 299           public static void Foo<T> (System.Predicate<T> predicate) {}
 300         }
 301 .fi
 302 The String ID for this method is
 303 .I M:FooType.Foo``1(System.Predicate{``0})
 304 , as
 305 .I ``0
 306 is the 0th generic parameter index which is bound to
 307 .I System.Predicate<T>
 308 \&.
 309 .SH DOCUMENTATION FORMAT
 310 .I monodocer
 311 generates documentation similar to the Ecma documentation format, as described
 312 in ECMA-335 3rd Edition, Partition IV, Chapter 7.
 313 .PP
 314 The principal difference from the ECMA format is that each type gets its own
 315 file, within a directory identical to the namespace of the type.
 316 .PP
 317 Most of the information within the documentation should
 318 .I not
 319 be edited.  This includes the type name (
 320 .I /Type/@FullName
 321 ), implemented interfaces (
 322 .I /Type/Interfaces
 323 ), member information (
 324 .I /Type/Members/Member/@MemberName
 325 ,
 326 .I /Type/Members/Member/MemberSignature
 327 ,
 328 .I /Type/Members/Member/MemberType
 329 ,
 330 .I /Type/Members/Member/Parameters
 331 , etc.).
 332 .PP
 333 What
 334 .I should
 335 be modified are all elements with the text
 336 .I To be added.
 337 , which are present under the
 338 .I //Docs
 339 elements (e.g.
 340 .I /Type/Docs
 341 ,
 342 .I /Type/Members/Member/Docs
 343 ).  The contents of the
 344 .I Docs
 345 element is
 346 .I identical
 347 in semantics and structure to the inline C# documentation format, consisting
 348 of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2).  The
 349 following are used within the element descriptions:
 350 .TP
 351 .I CREF
 352 Refers to a class (or member) reference, and is a string in the format
 353 described above in the
 354 .I STRING ID FORMAT
 355 section.
 356 .TP
 357 .I TEXT
 358 Non-XML text, and XML should not be nested.
 359 .I
 360 .TP
 361 .I XML
 362 Only XML elements should be nested (which indirectly may contain text), but
 363 non-whitespace text should not be an immediate child node.
 364 .TP
 365 .I XML_TEXT
 366 Free-form text and XML, so that other XML elements may be nested.
 367 .PP
 368 The following elements are used in documentation:
 369 .TP
 370 .I <block subset="SUBSET" type="TYPE">XML_TEXT</block>
 371 Create a block of text, similar in concept to a paragraph, but is used to
 372 create divisions within the text.  To some extent, a <block/> is equivalent to
 373 the HTML <h2/> tag.
 374 .Sp
 375 .I SUBSET
 376 should always be the value
 377 .I "none"
 378 \&.
 379 .Sp
 380 .I TYPE
 381 specifies the heading and formatting to use.  Recognized types are:
 382 .Sp
 383 .I behaviors
 384 Creates a section with the heading
 385 .I Operation
 386 \&.
 387 .Sp
 388 .I note
 389 Creates a section with the heading
 390 .I Note:
 391 \&.
 392 .Sp
 393 .I overrides
 394 Creates a section with the heading
 395 .I Note to Inheritors
 396 \&.
 397 .Sp
 398 .I usage
 399 Creates a section with the heading
 400 .I Usage
 401 \&.
 402 .TP
 403 .I <c>XML_TEXT</c>
 404 Set text in a code-like font (similar to the HTML <tt/> element).
 405 .TP
 406 .I <code lang="LANGUAGE">TEXT</code>
 407 Display multiple lines of text in a code-like font (similar to the HTML <pre/>
 408 element).
 409 .I LANGUAGE
 410 is the language this code block is for.  For example, if
 411 .I LANGUAGE
 412 is
 413 .B C#
 414 , then
 415 .I TEXT
 416 will get syntax highlighting for the C# language within the Mono Documentation
 417 Browser.
 418 .TP
 419 .I <example>XML_TEXT</example>
 420 Indicates an example that should be displayed specially.  For example:
 421 .nf
 422         <example>
 423           <para>An introductory paragraph.</para>
 424           <code lang="C#">
 425             class Example {
 426               public static void Main ()
 427               {
 428                 System.Console.WriteLine ("Hello, World!");
 429               }
 430             }
 431           </code>
 432         </example>
 433 .fi
 434 .TP
 435 .I <exception cref="CREF">XML_TEXT</exception>
 436 Identifies an exception that can be thrown by the documented member.
 437 .Sp
 438 .I <exception/>
 439 is a top-level element, and should be nested directly under the
 440 .I <Docs/>
 441 element.
 442 .Sp
 443 .I CREF
 444 is the exception type that is thrown, while
 445 .I XML_TEXT
 446 contains the circumstances that would cause
 447 .I CREF
 448 to be thrown.
 449 .nf
 450         <exception cref="T:System.ArgumentNullException">
 451           <paramref name="foo" /> was <see langword="null" />.
 452         </exception>
 453 .fi
 454 .TP
 455 .I <list>XML</list>
 456 Create a list or table of items.
 457 .I <list/>
 458 makes use of nested
 459 .I <item>XML</item>
 460 ,
 461 .I <listheader>XML</listheader>
 462 ,
 463 .I <term>XML_TEXT</term>
 464 , and
 465 .I <description>XML_TEXT</description>
 466 elements.
 467 .Sp
 468 .I Lists
 469 have the syntax:
 470 .nf
 471         <list type="bullet"> <!-- or type="number" -->
 472           <item><term>Bullet 1</term></item>
 473           <item><term>Bullet 2</term></item>
 474           <item><term>Bullet 3</term></item>
 475         </list>
 476 .fi
 477 .Sp
 478 .I Tables
 479 have the syntax:
 480 .nf
 481         <list type="table">
 482           <listheader> <!-- listheader bolds this row -->
 483             <term>Column 1</term>
 484             <description>Column 2</description>
 485             <description>Column 3</description>
 486           </listheader>
 487           <item>
 488             <term>Item 1-A</term>
 489             <description>Item 1-B</description>
 490             <description>Item 1-C</description>
 491           </item>
 492           <item>
 493             <term>Item 2-A</term>
 494             <description>Item 2-B</description>
 495             <description>Item 2-C</description>
 496           </item>
 497         </list>
 498 .fi
 499 .TP
 500 .I <para>XML_TEXT</para>
 501 Insert a paragraph of
 502 .I XML_TEXT
 503  .
 504 This is for use within other tags, such as
 505 .I <example/>
 506 ,
 507 .I <remarks/>
 508 ,
 509 .I <returns/>
 510 ,
 511 .I <term/>
 512 and
 513 .I <description/>
 514 (see
 515 .I <list/>
 516 , above), and most other elements.
 517 .Sp
 518 For example,
 519 .nf
 520         <para>This is a paragraph of text.</para>
 521 .fi
 522 .TP
 523 .I <param name="NAME">XML_TEXT</param>
 524 .I <param/>
 525 is a top-level element, and should be nested directly under the
 526 .I <Docs/>
 527 element.
 528 .Sp
 529 Describes the parameter
 530 .I NAME
 531 of the current constructor, method, or property:
 532 .nf
 533         <param name="count">
 534           A <see cref="T:System.Int32" /> containing the number
 535           of widgets to process.
 536         </param>
 537 .fi
 538 .TP
 539 .I <paramref name="NAME" />
 540 Indicates that
 541 .I NAME
 542 is a parameter.
 543 .Sp
 544 This usually renders
 545 .I NAME
 546 as italic text, so it is frequently (ab)used as an equivalent to the
 547 HTML <i/> element.  See the
 548 .I <exception/>
 549 documentation (above) for an example.
 550 .TP
 551 .I <permission cref="CREF">XML_TEXT</permission>
 552 Documentes the security accessibility requirements of the current member.
 553 .Sp
 554 .I <permission/>
 555 is a top-level element, and should be nested directly under the
 556 .I <Docs/>
 557 element.
 558 .Sp
 559 .I CREF
 560 is a type reference to the security permission required, while
 561 .I XML_TEXT
 562 is a description of why the permission is required.
 563 .nf
 564         <permission cref="T:System.Security.Permissions.FileIOPermission">
 565           Requires permission for reading and writing files. See
 566           <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
 567           <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
 568         </permission>
 569 .fi
 570 .TP
 571 .I <remarks>XML_TEXT</remarks>
 572 Contains detailed information about a member.
 573 .Sp
 574 .I <remarks/>
 575 is a top-level element, and should be nested directly under the
 576 .I <Docs/>
 577 element.
 578 .nf
 579         <remarks>Insert detailed information here.</remarks>
 580 .fi
 581 .TP
 582 .I <returns>XML_TEXT</returns>
 583 .Sp
 584 .I <remarks/>
 585 is a top-level element, and should be nested directly under the
 586 .I <Docs/>
 587 element.
 588 .Sp
 589 Describes the return value of a method:
 590 .nf
 591         <returns>
 592           A <see cref="T:System.Boolean" /> specifying whether
 593           or not the process can access
 594           <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
 595         </returns>
 596 .fi
 597 .TP
 598 .I <see cref="CREF" />
 599 Creates a link to the specified member within the current text:
 600 .nf
 601         <see cref="M:Some.Namespace.With.Type.Method" />
 602 .fi
 603 .TP
 604 .I <seealso cref="CREF" />
 605 .Sp
 606 .I <seealso/>
 607 is a top-level element, and should be nested directly under the
 608 .I <Docs/>
 609 element.
 610 .Sp
 611 Allows an entry to be generated for the
 612 .I See Also
 613 subclause.  Use
 614 .I <see/>
 615 to specify a link from within text.
 616 .nf
 617         <seealso cref="P:System.Exception.Message" />
 618 .fi
 619 .TP
 620 .I <since version="VERSION" />
 621 .Sp
 622 .I <since/>
 623 is a top-level element, and should be nested directly under the
 624 .I <Docs/>
 625 element.
 626 .Sp
 627 Permits specification of which version introduced the specified type or
 628 member.
 629 .nf
 630         <since version="Gtk# 2.4" />
 631 .fi
 632 .TP
 633 .I <summary>DESCRIPTION</summary>
 634 .Sp
 635 .I <summary/>
 636 is a top-level element, and should be nested directly under the
 637 .I <Docs/>
 638 element.
 639 .Sp
 640 Provides a (brief!) overview about a type or type member.
 641 .Sp
 642 This is usually displayed as part of a class declaration, and should be a
 643 reasonably short description of the type/member.  Use
 644 .I <remarks/>
 645 for more detailed information.
 646 .TP
 647 .I <typeparam name="NAME">DESCRPITION</typeparam>
 648 .I <typeparam/>
 649 is a top-level element, and should be nested directly under the
 650 .I <Docs/>
 651 element.
 652 .Sp
 653 This is used to describe type parameter for a generic type or generic method.
 654 .Sp
 655 .I NAME
 656 is the name of the type parameter, while
 657 .I DESCRIPTION
 658 contains a description of the parameter (what it's used for, what restrictions
 659 it must meet, etc.).
 660 .nf
 661         <typeparam name="T">The type of the underlying collection</typeparam>
 662 .fi
 663 .TP
 664 .I <typeparamref>
 665 Used to indicate that a word is a type parameter, for use within other text
 666 blocks (e.g. within
 667 .I <para/>
 668 ).
 669 .nf
 670         <para>If <typeparamref name="T" /> is a struct, then...</para>
 671 .fi
 672 .TP
 673 .I <value>DESCRIPTION</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 .nf
 681         <value>
 682           A <see cref="T:System.String" /> containing a widget name.
 683         </value>
 684 .fi
 685 .PP
 686 .SH SEE ALSO
 687 mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), monodocs2html(1)
 688 .SH MAILING LISTS
 689 .TP
 690 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
 691 .SH WEB SITE
 692 Visit http://www.mono-project.com for details