path: root/man/monodocer.1

.\" 
.\" monodocer manual page.
.\" (C) 2006 Jonathan Pryor
.\" Author:
.\"   Jonathan Pryor (jonpryor@vt.edu)
.\"
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.TH "monodocer" 1
.SH NAME
monodocer \- ECMA Documentation Format Support
.SH SYNOPSIS
.B monodocer
[OPTIONS]*
.SH OPTIONS
.TP
.I \-assembly:ASSEMBLY
.I ASSEMBLY
is a .NET assembly to generate documentation stubs for.
.Sp
Specify a file path or the name of a GAC'd assembly.
.TP
.I \-delete
Allow monodocer to delete members from documentation files.  
The only members deleted are for members which are no longer present within
the assembly.
.Sp
If a type is no longer present, the documentation file is
.I not
deleted, but is instead
.I renamed
to have a
.B .remove 
extension.
.TP
.I \-?, \-help
Show program argument information.
.TP
.I \-ignoremembers
Do not update members.
.Sp
This will add documentation stubs for added types, but will
.I not
add or remove documentation for any members of any type (including any added
types).
.TP
.I \-importslashdoc:FILE
.I FILE
is an XML file generated with the 
.B /doc:FILE
C# compiler flag (e.g.
.I mcs -doc:foo.xml foo.cs
).  Import the member documentation contained within
.I FILE
into the documentation format used by monodoc.
.TP
.I \-name:NAME
.I NAME
is the name of the project this documentation is for.
.Sp
This sets the 
.I /Overview/Title
element within the 
.I index.xml
file created at the directory specified by
.I -path
\&.
This is used by some programs for title information (e.g.
.I monodocs2html
).
.TP
.I \-namespace:NAMESPACE
Only update the types within the namespace
.I NAMESPACE
\&.
.TP
.I \-overrides
Include overridden methods in documentation.
.Sp
This normally isn't necessary, as the Mono Documentation Browser will provide a
link to the base type members anyway, as will
.I monodocs2html
if the base type is within the same assembly.
.TP
.I \-path:OUTPUT_DIR
.I OUTPUT_DIR
is the directory which will contain the new/updated documentation stubs.
.TP
.I \-pretty
Indent the XML files nicely.
.TP
.I \-since:SINCE
Create a <since/> element for added types and members with the value 
.I SINCE
\&.
.Sp
For example, when given
.I -since:"Gtk# 2.4"
an element will be inserted into the 
.I Docs
element for all added types and type members:
.nf
	<since version="Gtk# 2.4" />
.fi
The Mono Documentation Browser and 
.I monodocs2html
will use this element to specify in which version a member was added.
.TP
.I \-type:TYPE
Only create/update documentation for the type
.I TYPE
\&.
.TP
.I \-updateto:PATH
When updating documentation, write the updated documentation files into the
directory 
.I PATH
\&.
.TP
.I \-V, \-version
Display version and licensing information.
.PP
.SH DESCRIPTION
\fBmonodocer\fR has been obsoleted by \fBmdoc\fR(1).  See the
\fBmdoc-update\fR(1) man page.
.PP
.I 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.
.PP
The advantages are:
.TP
.I *
.B 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.)
.Sp
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.
.TP
.I *
.B Localization.
In-source documentation formats (such as 
.B /doc
) have no support for multiple human languages.  If you need to support more
than one human language for documentation purposes, 
.I monodocer
is useful as it permits each language to get its own directory, and 
.I monodocer
can add types/members for each separate documentation directory.
.TP
.I *
.B 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.
.I monodocer
allows the documentation to be kept 
.I completely
separate and distinct from the source code used to create the assembly.
.PP
To turn the 
.I 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:
.nf

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

.fi
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:
.nf

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

.fi
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.   
.PP
Once you have all of your files (.zip, .tree and .sources) you can
install them into the system with the following command:
.nf

        $ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`
  
.fi
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 
.I pkg-config 
invocation.
.SH 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 
.I member type prefix
, the full type name (namespace + name, separated by '.'), possibly followed
by the member name and other information.
.PP
Member type prefixes:
.TP
.I "E:"
The String ID refers to an event.  The event name follows the type name:
.I E:System.AppDomain.AssemblyLoad
.TP
.I "F:"
The String ID refers to a field.  The field name follows the type name:
.I F:System.Runtime.InteropServices.DllImportAttribute.SetLastError
.TP
.I "M:"
Refers to a constructor or method.  Constructors append 
.I .ctor
to the type name, while methods append the method name (with an optional count
of the number of generic parameters).
.Sp
If the constructor or method take arguments, these are listed within
parenthesis after the constructor/method name:
.Sp
.I M:System.Object..ctor
,
.I M:System.String..ctor(System.Char[])
,
.I M:System.String.Concat(System.Object)
,
.I M:System.Array.Sort``1(``0[])
,
.I M:System.Collections.Generic.List`1..ctor
,
.I M:System.Collections.Generic.List`1.Add(`0)
\&.
.TP
.I "N:"
Refers to a namespace, e.g.
.I N:System
.TP
.I "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
parenthesis:
.I P:System.String.Length
,
.I P:System.String.Chars(System.Int32)
\&.
.TP
.I "T:"
The String ID refers to a type, with the number of generic types appended:
.I T:System.String
,
.I T:System.Collections.Generic.List`1
.PP
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 '}'.
.PP
.B Unbound:
.I T:System.Collections.Generic.List`1
,
.I T:System.Collections.Generic.Dictionary`2
\&.
.PP
.B Bound:
.I T:System.Collections.Generic.List{System.Int32}
.I T:System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Predicate{System.String}}}
\&.
.PP
As you can see, bound variants can be arbitrarily complex (just like
generics).
.PP
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
.nf
	class FooType {
	  public static void Foo<T> (System.Predicate<T> predicate) {}
	}
.fi
The String ID for this method is
.I M:FooType.Foo``1(System.Predicate{``0})
, as 
.I ``0
is the 0th generic parameter index which is bound to 
.I System.Predicate<T>
\&.
.SH DOCUMENTATION FORMAT
.I monodocer
generates documentation similar to the Ecma documentation format, as described 
in ECMA-335 3rd Edition, Partition IV, Chapter 7.
.PP
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.
.PP
Most of the information within the documentation should
.I not
be edited.  This includes the type name (
.I /Type/@FullName
), implemented interfaces (
.I /Type/Interfaces
), member information (
.I /Type/Members/Member/@MemberName
,
.I /Type/Members/Member/MemberSignature
,
.I /Type/Members/Member/MemberType
,
.I /Type/Members/Member/Parameters
, etc.).
.PP
What 
.I should
be modified are all elements with the text
.I To be added.
, which are present under the 
.I //Docs
elements (e.g. 
.I /Type/Docs
,
.I /Type/Members/Member/Docs
).  The contents of the
.I Docs
element is
.I 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:
.TP
.I CREF
Refers to a class (or member) reference, and is a string in the format
described above in the
.I STRING ID FORMAT
section.
.TP
.I TEXT
Non-XML text, and XML should not be nested.
.I
.TP
.I XML
Only XML elements should be nested (which indirectly may contain text), but
non-whitespace text should not be an immediate child node.
.TP
.I XML_TEXT
Free-form text and XML, so that other XML elements may be nested.
.PP
The following elements are used in documentation:
.TP
.I <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.
.Sp
.I SUBSET
should always be the value
.I "none"
\&.
.Sp
.I TYPE
specifies the heading and formatting to use.  Recognized types are:
.Sp
.I behaviors
Creates a section with the heading
.I Operation
\&.
.Sp
.I note
Creates a section with the heading 
.I Note:
\&.
.Sp
.I overrides
Creates a section with the heading
.I Note to Inheritors
\&.
.Sp
.I usage
Creates a section with the heading
.I Usage
\&.
.TP
.I <c>XML_TEXT</c>
Set text in a code-like font (similar to the HTML <tt/> element).
.TP
.I <code lang="LANGUAGE">TEXT</code>
Display multiple lines of text in a code-like font (similar to the HTML <pre/>
element).
.I LANGUAGE
is the language this code block is for.  For example, if
.I LANGUAGE
is 
.B C#
, then 
.I TEXT
will get syntax highlighting for the C# language within the Mono Documentation
Browser.
.TP
.I <example>XML_TEXT</example>
Indicates an example that should be displayed specially.  For example:
.nf
	<example>
	  <para>An introductory paragraph.</para>
	  <code lang="C#">
	    class Example {
	      public static void Main ()
	      {
	        System.Console.WriteLine ("Hello, World!");
	      }
	    }
	  </code>
	</example>
.fi
.TP
.I <exception cref="CREF">XML_TEXT</exception>
Identifies an exception that can be thrown by the documented member.
.Sp
.I <exception/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
.I CREF
is the exception type that is thrown, while
.I XML_TEXT
contains the circumstances that would cause 
.I CREF
to be thrown.
.nf
	<exception cref="T:System.ArgumentNullException">
	  <paramref name="foo" /> was <see langword="null" />.
	</exception>
.fi
.TP
.I <list>XML</list>
Create a list or table of items.  
.I <list/>
makes use of nested
.I <item>XML</item>
,
.I <listheader>XML</listheader>
,
.I <term>XML_TEXT</term>
, and
.I <description>XML_TEXT</description>
elements.
.Sp
.I Lists
have the syntax:
.nf
	<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>
.fi
.Sp
.I Tables
have the syntax:
.nf
	<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>
.fi
.TP
.I <para>XML_TEXT</para>
Insert a paragraph of
.I XML_TEXT
 .
This is for use within other tags, such as 
.I <example/>
,
.I <remarks/>
,
.I <returns/>
,
.I <term/>
and 
.I <description/>
(see 
.I <list/>
, above), and most other elements.
.Sp
For example,
.nf
	<para>This is a paragraph of text.</para>
.fi
.TP
.I <param name="NAME">XML_TEXT</param>
.I <param/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Describes the parameter
.I NAME
of the current constructor, method, or property:
.nf
	<param name="count">
	  A <see cref="T:System.Int32" /> containing the number
	  of widgets to process.
	</param>
.fi
.TP
.I <paramref name="NAME" />
Indicates that
.I NAME
is a parameter.
.Sp
This usually renders 
.I NAME
as italic text, so it is frequently (ab)used as an equivalent to the
HTML <i/> element.  See the 
.I <exception/>
documentation (above) for an example.
.TP
.I <permission cref="CREF">XML_TEXT</permission>
Documentes the security accessibility requirements of the current member.
.Sp
.I <permission/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
.I CREF
is a type reference to the security permission required, while
.I XML_TEXT
is a description of why the permission is required.
.nf
	<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>
.fi
.TP
.I <remarks>XML_TEXT</remarks>
Contains detailed information about a member.
.Sp
.I <remarks/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.nf
	<remarks>Insert detailed information here.</remarks>
.fi
.TP
.I <returns>XML_TEXT</returns>
.Sp
.I <remarks/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Describes the return value of a method:
.nf
	<returns>
	  A <see cref="T:System.Boolean" /> specifying whether 
	  or not the process can access 
	  <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
	</returns>
.fi
.TP
.I <see cref="CREF" />
Creates a link to the specified member within the current text:
.nf
	<see cref="M:Some.Namespace.With.Type.Method" />
.fi
.TP
.I <seealso cref="CREF" />
.Sp
.I <seealso/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Allows an entry to be generated for the 
.I See Also
subclause.  Use 
.I <see/>
to specify a link from within text.
.nf
	<seealso cref="P:System.Exception.Message" />
.fi
.TP
.I <since version="VERSION" />
.Sp
.I <since/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Permits specification of which version introduced the specified type or
member.
.nf
	<since version="Gtk# 2.4" />
.fi
.TP
.I <summary>DESCRIPTION</summary>
.Sp
.I <summary/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Provides a (brief!) overview about a type or type member.
.Sp
This is usually displayed as part of a class declaration, and should be a
reasonably short description of the type/member.  Use
.I <remarks/>
for more detailed information.
.TP
.I <typeparam name="NAME">DESCRPITION</typeparam>
.I <typeparam/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
This is used to describe type parameter for a generic type or generic method.
.Sp
.I NAME
is the name of the type parameter, while
.I DESCRIPTION
contains a description of the parameter (what it's used for, what restrictions
it must meet, etc.).
.nf
	<typeparam name="T">The type of the underlying collection</typeparam>
.fi
.TP
.I <typeparamref>
Used to indicate that a word is a type parameter, for use within other text
blocks (e.g. within 
.I <para/>
).
.nf
	<para>If <typeparamref name="T" /> is a struct, then...</para>
.fi
.TP
.I <value>DESCRIPTION</value>
.I <value/>
is a top-level element, and should be nested directly under the 
.I <Docs/>
element.
.Sp
Allows a property to be described.
.nf
	<value>
	  A <see cref="T:System.String" /> containing a widget name.
	</value>
.fi
.PP
.SH SEE ALSO
mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), monodocs2html(1)
.SH MAILING LISTS
.TP
Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
.SH WEB SITE
Visit http://www.mono-project.com for details