monodocer(1)

🌸 monodocer(1) 🌸

okay bestie, vibe check: this is the General Commands Manual entry for monodocer, and she is long. grab a strawberry and sit down. 🍓 this is part 1, so don't go anywhere.

---

💖 NAME 💖

monodocer — ECMA Documentation Format Support. that's it, that's the whole name. slay.

---

✨ SYNOPSIS ✨

monodocer [OPTIONS]*

---

🎀 OPTIONS 🎀

• -assembly:ASSEMBLY — ASSEMBLY is a .NET assembly you want documentation stubs generated for. you can hand her a file path, or just the name of a GAC'd assembly. either works, she's flexible like that.
• -delete — this lets monodocer actually delete members from your documentation files. 😳 the only members she deletes are the ones that are no longer present inside the assembly. and if a whole type is gone, the documentation file does not get deleted — it gets renamed to have a .remove extension instead. gentle queen behavior.
• -?, -help — show program argument information.
• -ignoremembers — do not update members. this will add documentation stubs for added types, but it will not add or remove documentation for any members of any type (including the members of any added types). she's just not touching members. periodt.
• -importslashdoc:FILE — FILE is an XML file generated with the /doc:FILE C# compiler flag (e.g. mcs -doc:foo.xml foo.cs). this imports the member documentation contained within FILE into the documentation format used by monodoc. importing your lore, fr fr.
• -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. some programs use this for title information (e.g. monodocs2html).
• -namespace:NAMESPACE — only update the types within the namespace NAMESPACE. narrow it down, bestie.
• -overrides — include overridden methods in documentation. normally this isn't necessary, because the Mono Documentation Browser will provide a link to the base type members anyway, and so will monodocs2html if the base type is within the same assembly. so like, it's optional-optional.
• -path:OUTPUT_DIR — OUTPUT_DIR is the directory which will contain the new/updated documentation stubs. your home base.
• -pretty — indent the XML files nicely. it's giving aesthetic. 💅
• -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. iconic historical record keeping.

• -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. the receipts.

---

🌈 DESCRIPTION 🌈

okay so the headline news first, no burying the lede: monodocer has been obsoleted by mdoc(1). 👀 go see the mdoc-update(1) man page. she's retired, but we still respect her legacy.

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 docs live outside the code, and honestly? that's the whole point.

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. 😭 like the docs are bigger than the thing they describe.

• 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, because it permits each language to get its own directory, and monodocer can add types/members for each separate documentation directory. multilingual queen 🌍
• 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, because 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. boundaries! 🫶

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 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) .

• 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 parenthesis: 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 💖

okay bestie, so monodocer writes docs that look a lot like the Ecma documentation format — the one described in ECMA-335 3rd Edition, Partition IV, Chapter 7. iconic lineage honestly.

The big difference from the Ecma format? Every type gets its own file, living inside a directory that's identical to the namespace of the type. cute and organized, we love a folder structure moment. 🗂️

---

🙈 what you should NOT touch (hands off, bestie)

Most of the stuff in the docs should not be edited. Like, at all. That 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 you SHOULD touch

What should be modified are all the elements with the text To be added. — those live under the //Docs elements (like /Type/Docs, /Type/Members/Member/Docs).

The contents of the Docs element is identical in semantics and structure to the inline C# documentation format — made up of these elements, listed in ECMA-334 3rd Edition, Annex E, Section 2. And here's the glossary of terms used inside the element descriptions, no gatekeeping:

• 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 ELEMENTS (the whole roster, no skips)

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 it's used to create divisions within the text. To some extent, a <block/> is equivalent to the HTML <h2/> tag. lowkey a heading in disguise. 👑

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). it's giving typewriter chic. ⌨️

<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. So for example, if LANGUAGE is C#, then TEXT will get syntax highlighting for the C# language within the Mono Documentation Browser. pretty. ✨

<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. no nesting it in random places bestie, it's a main character.

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. 😭 we've all done it. See the <exception/> documentation (above) for an example.

<permission cref="CREF">XML_TEXT</permission>

Documentes the security accessibility requirements of the current member. (yes, "Documentes" — that's the original's spelling, we respect the typo in this house 💅)

<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. (yes, it says <remarks/> here — that's exactly what the page says, don't come for me 🫶)

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. yes, brief, the parentheses are doing a lot of work there, listen to them. 😌

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

---

and that's the whole page bestie!! this one's from the monodocer(1) manual page, and it's the Mono documentation tooling era of things 💜 go forth and document your parameters, your typeparams, and your very brief summaries. slay. 💅✨