Provided by: monodoc-base_3.2.8+dfsg-4ubuntu1_all bug

NAME

       monodocer - ECMA Documentation Format Support

SYNOPSIS

       monodocer [OPTIONS]*

OPTIONS

       -assembly:ASSEMBLY
              ASSEMBLY is a .NET assembly to generate documentation stubs for.

              Specify a file path or the name of a GAC'd assembly.

       -delete
              Allow  monodocer  to  delete  members  from  documentation files.  The only members
              deleted are for members which are no longer present within the assembly.

              If a type is no longer present, the documentation  file  is  not  deleted,  but  is
              instead renamed to have a .remove extension.

       -?, -help
              Show program argument information.

       -ignoremembers
              Do not update members.

              This  will  add  documentation  stubs  for  added types, but will not add or remove
              documentation for any members of any type (including any added types).

       -importslashdoc:FILE
              FILE is an XML file generated with  the  /doc:FILE  C#  compiler  flag  (e.g.   mcs
              -doc:foo.xml  foo.cs ).  Import the member documentation contained within FILE into
              the documentation format used by monodoc.

       -name:NAME
              NAME is the name of the project this documentation is for.

              This sets the /Overview/Title element within the  index.xml  file  created  at  the
              directory specified by -path .  This is used by some programs for title information
              (e.g.  monodocs2html ).

       -namespace:NAMESPACE
              Only update the types within the namespace NAMESPACE .

       -overrides
              Include overridden methods in documentation.

              This normally isn't necessary, as the Mono Documentation  Browser  will  provide  a
              link  to  the  base  type members anyway, as will monodocs2html if the base type is
              within the same assembly.

       -path:OUTPUT_DIR
              OUTPUT_DIR is the directory which will contain the new/updated documentation stubs.

       -pretty
              Indent the XML files nicely.

       -since:SINCE
              Create a <since/> element for added types and members with the value SINCE .

              For example, when given -since:"Gtk# 2.4" an element will be inserted into the Docs
              element for all added types and type members:
                   <since version="Gtk# 2.4" />
              The  Mono  Documentation Browser and monodocs2html will use this element to specify
              in which version a member was added.

       -type:TYPE
              Only create/update documentation for the type TYPE .

       -updateto:PATH
              When updating  documentation,  write  the  updated  documentation  files  into  the
              directory PATH .

       -V, -version
              Display version and licensing information.

DESCRIPTION

       monodocer has been obsoleted by mdoc(1).  See the mdoc-update(1) man page.

       monodocer  is  a  program  that  creates XML documentation stubs in the ECMA Documentation
       Format.  It does not rely on documentation found within the source code.

       The advantages are:

       *      Code readability.  Good documentation is frequently (a)  verbose,  and  (b)  filled
              with  examples.   (For  comparison, compare Microsoft .NET Framework documentation,
              which is often a page or more of docs for each member,  to  JavaDoc  documentation,
              which can often be a sentence for each member.)

              Inserting  good  documentation into the source code can frequently bloat the source
              file, as the documentation can be longer than  the  actual  method  that  is  being
              documented.

       *      Localization.   In-source documentation formats (such as /doc ) have no support for
              multiple human languages.  If you need to support more than one human language  for
              documentation  purposes, monodocer is useful as it permits each language to get its
              own directory, and monodocer can add types/members for each separate  documentation
              directory.

       *      Administration.   It's  not  unusual to have separate documentation and development
              teams.  It's also possible that the documentation team will have minimal experience
              with   the   programming  language  being  used.   In  such  circumstances,  inline
              documentation is not desirable as the documentation team could inadvertantly insert
              an error into the source code while updating the documentation.  Alternatively, you
              may not want the documentation team to have access to the source code for  security
              reasons.   monodocer  allows  the  documentation to be kept completely separate and
              distinct from the source code used to create the assembly.

       To turn the monodocer documentation into something  that  can  be  consumed  by  the  Mono
       Documentation  Browser  (the  desktop  help  browser,  or  the web interface for it) it is
       necessary to compile the documentation into a  packed  format.   This  is  done  with  the
       mdassembler tool, for example, you could use this toolchain like this:

            $ monodocer -assembly:MyWidgets -path:generated_docs
            $ mdassembler --ecma generated_docs -out:MyWidgets

       The  above  would generate a MyWidgets.zip and a MyWidgets.tree that can then be installed
       in the system.   In addition to the two files (.zip and .tree) you must provide a .sources
       file which describes where in the help system the documentation should be hooked up, it is
       a very simple XML file, like this:

       <?xml version="1.0"?>
       <monodoc>
         <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>
       </monodoc>

       The above configuration file describes that the  documentation  is  in  ECMA  format  (the
       compiled  version) that the base file name is MyWidgets and that it should be hooked up in
       the "classlib-gnome" part of the tree.   If you want to look at the various nodes  defined
       in  the  documentation,  you  can look at monodoc.xml file which is typically installed in
       /usr/lib/monodoc/monodoc.xml.

       Once you have all of your files (.zip, .tree and .sources) you can install them  into  the
       system with the following command:

               $ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`

       The  above  will  copy the files into the directory that Monodoc has registered (you might
       need root permissions to do this).   The actual directory is returned  by  the  pkg-config
       invocation.

STRING ID FORMAT

       String  IDs are used to refer to a type or member of a type.  String IDs are documented in
       ECMA-334 3rd Edition, Annex E.3.1.  They consist of a member type prefix , the  full  type
       name  (namespace + name, separated by '.'), possibly followed by the member name and other
       information.

       Member type prefixes:

       E:     The String ID  refers  to  an  event.   The  event  name  follows  the  type  name:
              E:System.AppDomain.AssemblyLoad

       F:     The  String  ID  refers  to  a  field.   The  field  name  follows  the  type name:
              F:System.Runtime.InteropServices.DllImportAttribute.SetLastError

       M:     Refers to a constructor or method.  Constructors append .ctor  to  the  type  name,
              while  methods  append  the  method  name  (with an optional count of the number of
              generic parameters).

              If the constructor or method take arguments, these are  listed  within  paranthesis
              after the constructor/method name:

              M:System.Object..ctor        ,        M:System.String..ctor(System.Char[])        ,
              M:System.String.Concat(System.Object)     ,     M:System.Array.Sort``1(``0[])     ,
              M:System.Collections.Generic.List`1..ctor                                         ,
              M:System.Collections.Generic.List`1.Add(`0) .

       N:     Refers to a namespace, e.g.  N:System

       P:     Refers to a property.  If the property is  an  indexer  or  takes  parameters,  the
              parameter  types  are  appended to the property name and enclosed with paranthesis:
              P:System.String.Length , P:System.String.Chars(System.Int32) .

       T:     The String ID refers to  a  type,  with  the  number  of  generic  types  appended:
              T:System.String , T:System.Collections.Generic.List`1

       To  make  matters  more interesting, generic types & members have two representations: the
       "unbound" representation (shown in examples above), in which class names have the count of
       generic  parameters  appended  to  their name.  There is also a "bound" representation, in
       which the binding of generic parameters is listed within '{' and '}'.

       Unbound: T:System.Collections.Generic.List`1 , T:System.Collections.Generic.Dictionary`2 .

       Bound:                                     T:System.Collections.Generic.List{System.Int32}
       T:System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Predicate{System.String}}}
       .

       As you can see, bound variants can be arbitrarily complex (just like generics).

       Furthermore, if a generic parameter is bound to the generic parameter of a type or method,
       the "index" of the type/method's generic parameter is used as the binding, so given
            class FooType {
              public static void Foo<T> (System.Predicate<T> predicate) {}
            }
       The  String  ID for this method is M:FooType.Foo``1(System.Predicate{``0}) , as ``0 is the
       0th generic parameter index which is bound to System.Predicate<T> .

DOCUMENTATION FORMAT

       monodocer generates documentation similar to the Ecma documentation format,  as  described
       in ECMA-335 3rd Edition, Partition IV, Chapter 7.

       The  principal difference from the ECMA format is that each type gets its own file, within
       a directory identical to the namespace of the type.

       Most of the information within the documentation should not be edited.  This includes  the
       type  name  (  /Type/@FullName  ),  implemented  interfaces  (  /Type/Interfaces ), member
       information ( /Type/Members/Member/@MemberName  ,  /Type/Members/Member/MemberSignature  ,
       /Type/Members/Member/MemberType , /Type/Members/Member/Parameters , etc.).

       What  should  be modified are all elements with the text To be added.  , which are present
       under the //Docs elements (e.g.  /Type/Docs , /Type/Members/Member/Docs ).   The  contents
       of the Docs element is identical in semantics and structure to the inline C# documentation
       format, consisting of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2).
       The following are used within the element descriptions:

       CREF   Refers  to  a  class (or member) reference, and is a string in the format described
              above in the STRING ID FORMAT section.

       TEXT   Non-XML text, and XML should not be nested.

       XML    Only XML elements should be nested (which indirectly may contain  text),  but  non-
              whitespace text should not be an immediate child node.

       XML_TEXT
              Free-form text and XML, so that other XML elements may be nested.

       The following elements are used in documentation:

       <block subset="SUBSET" type="TYPE">XML_TEXT</block>
              Create  a  block  of text, similar in concept to a paragraph, but is used to create
              divisions within the text.  To some extent, a <block/> is equivalent  to  the  HTML
              <h2/> tag.

              SUBSET should always be the value none .

              TYPE specifies the heading and formatting to use.  Recognized types are:

              behaviors Creates a section with the heading Operation .

              note Creates a section with the heading Note: .

              overrides Creates a section with the heading Note to Inheritors .

              usage Creates a section with the heading Usage .

       <c>XML_TEXT</c>
              Set text in a code-like font (similar to the HTML <tt/> element).

       <code lang="LANGUAGE">TEXT</code>
              Display  multiple  lines  of  text  in a code-like font (similar to the HTML <pre/>
              element).  LANGUAGE is the language this  code  block  is  for.   For  example,  if
              LANGUAGE  is C# , then TEXT will get syntax highlighting for the C# language within
              the Mono Documentation Browser.

       <example>XML_TEXT</example>
              Indicates an example that should be displayed specially.  For example:
                   <example>
                     <para>An introductory paragraph.</para>
                     <code lang="C#">
                       class Example {
                         public static void Main ()
                         {
                           System.Console.WriteLine ("Hello, World!");
                         }
                       }
                     </code>
                   </example>

       <exception cref="CREF">XML_TEXT</exception>
              Identifies an exception that can be thrown by the documented member.

              <exception/> is a top-level element,  and  should  be  nested  directly  under  the
              <Docs/> element.

              CREF   is   the  exception  type  that  is  thrown,  while  XML_TEXT  contains  the
              circumstances that would cause CREF to be thrown.
                   <exception cref="T:System.ArgumentNullException">
                     <paramref name="foo" /> was <see langword="null" />.
                   </exception>

       <list>XML</list>
              Create a list or table of items.  <list/> makes use of  nested  <item>XML</item>  ,
              <listheader>XML</listheader>        ,       <term>XML_TEXT</term>       ,       and
              <description>XML_TEXT</description> elements.

              Lists have the syntax:
                   <list type="bullet"> <!-- or type="number" -->
                     <item><term>Bullet 1</term></item>
                     <item><term>Bullet 2</term></item>
                     <item><term>Bullet 3</term></item>
                   </list>

              Tables have the syntax:
                   <list type="table">
                     <listheader> <!-- listheader bolds this row -->
                       <term>Column 1</term>
                       <description>Column 2</description>
                       <description>Column 3</description>
                     </listheader>
                     <item>
                       <term>Item 1-A</term>
                       <description>Item 1-B</description>
                       <description>Item 1-C</description>
                     </item>
                     <item>
                       <term>Item 2-A</term>
                       <description>Item 2-B</description>
                       <description>Item 2-C</description>
                     </item>
                   </list>

       <para>XML_TEXT</para>
              Insert a paragraph of XML_TEXT
               .  This is for use within other tags, such as <example/> , <remarks/> , <returns/>
              , <term/> and <description/> (see <list/> , above), and most other elements.

              For example,
                   <para>This is a paragraph of text.</para>

       <param name="NAME">XML_TEXT</param>
              <param/>  is  a  top-level element, and should be nested directly under the <Docs/>
              element.

              Describes the parameter NAME of the current constructor, method, or property:
                   <param name="count">
                     A <see cref="T:System.Int32" /> containing the number
                     of widgets to process.
                   </param>

       <paramref name="NAME" />
              Indicates that NAME is a parameter.

              This usually renders NAME as italic text,  so  it  is  frequently  (ab)used  as  an
              equivalent  to  the  HTML <i/> element.  See the <exception/> documentation (above)
              for an example.

       <permission cref="CREF">XML_TEXT</permission>
              Documentes the security accessibility requirements of the current member.

              <permission/> is a top-level element, and  should  be  nested  directly  under  the
              <Docs/> element.

              CREF  is  a type reference to the security permission required, while XML_TEXT is a
              description of why the permission is required.
                   <permission cref="T:System.Security.Permissions.FileIOPermission">
                     Requires permission for reading and writing files. See
                     <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
                     <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
                   </permission>

       <remarks>XML_TEXT</remarks>
              Contains detailed information about a member.

              <remarks/> is a top-level element, and should be nested directly under the  <Docs/>
              element.
                   <remarks>Insert detailed information here.</remarks>

       <returns>XML_TEXT</returns>

              <remarks/>  is a top-level element, and should be nested directly under the <Docs/>
              element.

              Describes the return value of a method:
                   <returns>
                     A <see cref="T:System.Boolean" /> specifying whether
                     or not the process can access
                     <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
                   </returns>

       <see cref="CREF" />
              Creates a link to the specified member within the current text:
                   <see cref="M:Some.Namespace.With.Type.Method" />

       <seealso cref="CREF" />

              <seealso/> is a top-level element, and should be nested directly under the  <Docs/>
              element.

              Allows  an entry to be generated for the See Also subclause.  Use <see/> to specify
              a link from within text.
                   <seealso cref="P:System.Exception.Message" />

       <since version="VERSION" />

              <since/> is a top-level element, and should be nested directly  under  the  <Docs/>
              element.

              Permits specification of which version introduced the specified type or member.
                   <since version="Gtk# 2.4" />

       <summary>DESCRIPTION</summary>

              <summary/>  is a top-level element, and should be nested directly under the <Docs/>
              element.

              Provides a (brief!) overview about a type or type member.

              This is usually displayed  as  part  of  a  class  declaration,  and  should  be  a
              reasonably  short description of the type/member.  Use <remarks/> for more detailed
              information.

       <typeparam name="NAME">DESCRPITION</typeparam>
              <typeparam/> is a top-level element,  and  should  be  nested  directly  under  the
              <Docs/> element.

              This is used to describe type parameter for a generic type or generic method.

              NAME is the name of the type parameter, while DESCRIPTION contains a description of
              the parameter (what it's used for, what restrictions it must meet, etc.).
                   <typeparam name="T">The type of the underlying collection</typeparam>

       <typeparamref>
              Used to indicate that a word is a type parameter, for use within other text  blocks
              (e.g. within <para/> ).
                   <para>If <typeparamref name="T" /> is a struct, then...</para>

       <value>DESCRIPTION</value>
              <value/>  is  a  top-level element, and should be nested directly under the <Docs/>
              element.

              Allows a property to be described.
                   <value>
                     A <see cref="T:System.String" /> containing a widget name.
                   </value>

SEE ALSO

       mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), monodocs2html(1)

MAILING LISTS

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

WEB SITE

       Visit http://www.mono-project.com for details

                                                                                     monodocer(1)