Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
monodocer(1)		    General Commands Manual		  monodocer(1)

       monodocer - ECMA	Documentation Format Support

       monodocer [OPTIONS]*

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

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

	      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.

	      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 (includ-
	      ing any added types).

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

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

	      Only update the types within the namespace NAMESPACE .

	      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.

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

	      Indent the XML files nicely.

	      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 in-
	      serted into the Docs element for all added types and  type  mem-
		   <since version="Gtk#	2.4" />
	      The  Mono	 Documentation Browser and monodocs2html will use this
	      element to specify in which version a member was added.

	      Only create/update documentation for the type TYPE .

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

       -V, -version
	      Display version and licensing information.

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

       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	Micro-
	      soft .NET	Framework documentation, which is often	a page or more
	      of docs for each member, to JavaDoc documentation, which can of-
	      ten 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  documenta-
	      tion team	will have minimal experience with the programming lan-
	      guage 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 documen-
	      tation.	Alternatively, you may not want	the documentation team
	      to have access to	the source code	for  security  reasons.	  mon-
	      odocer  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	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"?>
	 <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>

       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 docu-
       mentation, you can look at monodoc.xml  file  which  is	typically  in-
       stalled in /usr/lib/monodoc/monodoc.xml.

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

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

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

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

       M:     Refers to	a constructor or method.  Constructors append .ctor to
	      the type name, while methods append the method name (with	an op-
	      tional 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.Ar-
	      ray.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 rep-
       resentations:  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 bind-
       ing of generic parameters is listed within '{' and '}'.

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

       Bound: T:System.Collections.Generic.List{System.Int32} T:System.Collec-
       tions.Generic.List{System.Predicate{System.String}}} .

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

       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.Predi-
       cate{``0})  ,  as ``0 is	the 0th	generic	parameter index	which is bound
       to System.Predicate_T_ .

       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

       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/@Mem-
       berName	,  /Type/Members/Member/MemberSignature	 ,  /Type/Members/Mem-
       ber/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 iden-
       tical 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

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

       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 .

	      Set text in a code-like font (similar to	the  HTML  <tt/>  ele-

       _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 Doc-
	      umentation Browser.

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

       _exception cref="CREF"_XML_TEXT_/exception_
	      Identifies an exception that can be  thrown  by  the  documented

	      _exception/_  is	a  top-level element, and should be nested di-
	      rectly under the _Docs/_ element.

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

	      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_

	      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>

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

	      Insert a paragraph of XML_TEXT
	       .  This is for use within other tags, such as _example/_	, _re-
	      marks/_ ,	_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.

       _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  cur-
	      rent member.

	      _permission/_  is	 a top-level element, and should be nested di-
	      rectly 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 re-
		   <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" />.

	      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>


	      _remarks/_ is a top-level	element, and should be nested directly
	      under the	_Docs/_	element.

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

       _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/_ 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 di-
	      rectly 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 con-
	      tains 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>

	      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/_ is a top-level element, and should be  nested  directly
	      under the	_Docs/_	element.

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

       mdassembler(1),	mdcs2ecma(1),  mdnormalizer(1),	 mdvalidator(1),  mon-

       Visit  for  de-

       Visit for details



Want to link to this manual page? Use this URL:

home | help