Specify a file path or the name of a GAC'd assembly.
If a type is no longer present, the documentation file is not deleted, but is instead renamed to have a .remove extension.
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).
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 ).
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.
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.
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:
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.
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.
Member type prefixes:
If the constructor or method take arguments, these are listed within parenthesis 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) .
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>
.
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:
The following elements are used in documentation:
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 .
<example>
<para>An introductory paragraph.</para>
<code lang="C#">
class Example {
public static void Main ()
{
System.Console.WriteLine ("Hello, World!");
}
}
</code>
</example>
<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>
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>
For example,
<para>This is a paragraph of text.</para>
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>
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/> 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/> is a top-level element, and should be nested directly under the <Docs/> element.
<remarks>Insert detailed information here.</remarks>
<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="M:Some.Namespace.With.Type.Method" />
<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/> 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/> 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.
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>
<para>If <typeparamref name="T" /> is a struct, then...</para>
Allows a property to be described.
<value>
A <see cref="T:System.String" /> containing a widget name.
</value>