1monodocer(1) General Commands Manual monodocer(1)
2
6 monodocer - ECMA Documentation Format Support
7
9 monodocer [OPTIONS]*
10
12 -assembly:ASSEMBLY
13 ASSEMBLY is a .NET assembly to generate documentation stubs for.
14 Specify a file path or the name of a GAC'd assembly.
16 -delete
18 Allow monodocer to delete members from documentation files. The
19 only members deleted are for members which are no longer present
20 within the assembly.
21 If a type is no longer present, the documentation file is not
23 deleted, but is instead renamed to have a .remove extension.
24 -?, -help
26 Show program argument information.
27 -ignoremembers
29 Do not update members.
30 This will add documentation stubs for added types, but will not
32 add or remove documentation for any members of any type (includ‐
33 ing any added types).
34 -importslashdoc:FILE
36 FILE is an XML file generated with the /doc:FILE C# compiler
37 flag (e.g. mcs -doc:foo.xml foo.cs ). Import the member docu‐
38 mentation contained within FILE into the documentation format
39 used by monodoc.
40 -name:NAME
42 NAME is the name of the project this documentation is for.
43 This sets the /Overview/Title element within the index.xml file
45 created at the directory specified by -path . This is used by
46 some programs for title information (e.g. monodocs2html ).
47 -namespace:NAMESPACE
49 Only update the types within the namespace NAMESPACE .
50 -overrides
52 Include overridden methods in documentation.
53 This normally isn't necessary, as the Mono Documentation Browser
55 will provide a link to the base type members anyway, as will
56 monodocs2html if the base type is within the same assembly.
57 -path:OUTPUT_DIR
59 OUTPUT_DIR is the directory which will contain the new/updated
60 documentation stubs.
61 -pretty
63 Indent the XML files nicely.
64 -since:SINCE
66 Create a <since/> element for added types and members with the
67 value SINCE .
68 For example, when given -since:"Gtk# 2.4" an element will be
70 inserted into the Docs element for all added types and type mem‐
71 bers:
72 <since version="Gtk# 2.4" />
73 The Mono Documentation Browser and monodocs2html will use this
74 element to specify in which version a member was added.
75 -type:TYPE
77 Only create/update documentation for the type TYPE .
78 -updateto:PATH
80 When updating documentation, write the updated documentation
81 files into the directory PATH .
82 -V, -version
84 Display version and licensing information.
85
87 monodocer has been obsoleted by mdoc(1). See the mdoc-update(1) man
88 page.
89 monodocer is a program that creates XML documentation stubs in the ECMA
91 Documentation Format. It does not rely on documentation found within
92 the source code.
93 The advantages are:
95 * Code readability. Good documentation is frequently (a) verbose,
97 and (b) filled with examples. (For comparison, compare Micro‐
98 soft .NET Framework documentation, which is often a page or more
99 of docs for each member, to JavaDoc documentation, which can
100 often be a sentence for each member.)
101 Inserting good documentation into the source code can frequently
103 bloat the source file, as the documentation can be longer than
104 the actual method that is being documented.
105 * Localization. In-source documentation formats (such as /doc )
107 have no support for multiple human languages. If you need to
108 support more than one human language for documentation purposes,
109 monodocer is useful as it permits each language to get its own
110 directory, and monodocer can add types/members for each separate
111 documentation directory.
112 * Administration. It's not unusual to have separate documentation
114 and development teams. It's also possible that the documenta‐
115 tion team will have minimal experience with the programming lan‐
116 guage being used. In such circumstances, inline documentation
117 is not desirable as the documentation team could inadvertantly
118 insert an error into the source code while updating the documen‐
119 tation. Alternatively, you may not want the documentation team
120 to have access to the source code for security reasons. mon‐
121 odocer allows the documentation to be kept completely separate
122 and distinct from the source code used to create the assembly.
123 To turn the monodocer documentation into something that can be consumed
125 by the Mono Documentation Browser (the desktop help browser, or the web
126 interface for it) it is necessary to compile the documentation into a
127 packed format. This is done with the mdassembler tool, for example,
128 you could use this toolchain like this:
129 $ monodocer -assembly:MyWidgets -path:generated_docs
131 $ mdassembler --ecma generated_docs -out:MyWidgets
132 The above would generate a MyWidgets.zip and a MyWidgets.tree that can
134 then be installed in the system. In addition to the two files (.zip
135 and .tree) you must provide a .sources file which describes where in
136 the help system the documentation should be hooked up, it is a very
137 simple XML file, like this:
138 <?xml version="1.0"?>
140 <monodoc>
141 <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>
142 </monodoc>
143 The above configuration file describes that the documentation is in
145 ECMA format (the compiled version) that the base file name is MyWidgets
146 and that it should be hooked up in the "classlib-gnome" part of the
147 tree. If you want to look at the various nodes defined in the docu‐
148 mentation, you can look at monodoc.xml file which is typically
149 installed in /usr/lib/monodoc/monodoc.xml.
150 Once you have all of your files (.zip, .tree and .sources) you can
152 install them into the system with the following command:
153 $ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`
155 The above will copy the files into the directory that Monodoc has reg‐
157 istered (you might need root permissions to do this). The actual
158 directory is returned by the pkg-config invocation.
159
161 String IDs are used to refer to a type or member of a type. String IDs
162 are documented in ECMA-334 3rd Edition, Annex E.3.1. They consist of a
163 member type prefix , the full type name (namespace + name, separated by
164 '.'), possibly followed by the member name and other information.
165 Member type prefixes:
167 E: The String ID refers to an event. The event name follows the
169 type name: E:System.AppDomain.AssemblyLoad
170 F: The String ID refers to a field. The field name follows the
172 type name: F:System.Runtime.InteropServices.DllImportAt‐
173 tribute.SetLastError
174 M: Refers to a constructor or method. Constructors append .ctor to
176 the type name, while methods append the method name (with an
177 optional count of the number of generic parameters).
178 If the constructor or method take arguments, these are listed
180 within parenthesis after the constructor/method name:
181 M:System.Object..ctor , M:System.String..ctor(System.Char[]) ,
183 M:System.String.Concat(System.Object) , M:Sys‐
184 tem.Array.Sort``1(``0[]) , M:System.Collec‐
185 tions.Generic.List`1..ctor , M:System.Collec‐
186 tions.Generic.List`1.Add(`0) .
187 N: Refers to a namespace, e.g. N:System
189 P: Refers to a property. If the property is an indexer or takes
191 parameters, the parameter types are appended to the property
192 name and enclosed with parenthesis: P:System.String.Length ,
193 P:System.String.Chars(System.Int32) .
194 T: The String ID refers to a type, with the number of generic types
196 appended: T:System.String , T:System.Collections.Generic.List`1
197 To make matters more interesting, generic types & members have two rep‐
199 resentations: the "unbound" representation (shown in examples above),
200 in which class names have the count of generic parameters appended to
201 their name. There is also a "bound" representation, in which the bind‐
202 ing of generic parameters is listed within '{' and '}'.
203 Unbound: T:System.Collections.Generic.List`1 , T:System.Collec‐
205 tions.Generic.Dictionary`2 .
206 Bound: T:System.Collections.Generic.List{System.Int32} T:System.Collec‐
208 tions.Generic.Dictionary{System.String,System.Collec‐
209 tions.Generic.List{System.Predicate{System.String}}} .
210 As you can see, bound variants can be arbitrarily complex (just like
212 generics).
213 Furthermore, if a generic parameter is bound to the generic parameter
215 of a type or method, the "index" of the type/method's generic parameter
216 is used as the binding, so given
217 class FooType {
218 public static void Foo<T> (System.Predicate<T> predicate) {}
219 }
220 The String ID for this method is M:FooType.Foo``1(System.Predi‐
221 cate{``0}) , as ``0 is the 0th generic parameter index which is bound
222 to System.Predicate<T> .
223
225 monodocer generates documentation similar to the Ecma documentation
226 format, as described in ECMA-335 3rd Edition, Partition IV, Chapter 7.
227 The principal difference from the ECMA format is that each type gets
229 its own file, within a directory identical to the namespace of the
230 type.
231 Most of the information within the documentation should not be edited.
233 This includes the type name ( /Type/@FullName ), implemented interfaces
234 ( /Type/Interfaces ), member information ( /Type/Members/Member/@Mem‐
235 berName , /Type/Members/Member/MemberSignature , /Type/Members/Mem‐
236 ber/MemberType , /Type/Members/Member/Parameters , etc.).
237 What should be modified are all elements with the text To be added. ,
239 which are present under the //Docs elements (e.g. /Type/Docs ,
240 /Type/Members/Member/Docs ). The contents of the Docs element is iden‐
241 tical in semantics and structure to the inline C# documentation format,
242 consisting of these elements (listed in ECMA-334 3rd Edition, Annex E,
243 Section 2). The following are used within the element descriptions:
244 CREF Refers to a class (or member) reference, and is a string in the
246 format described above in the STRING ID FORMAT section.
247 TEXT Non-XML text, and XML should not be nested.
249 XML Only XML elements should be nested (which indirectly may contain
251 text), but non-whitespace text should not be an immediate child
252 node.
253 XML_TEXT
255 Free-form text and XML, so that other XML elements may be
256 nested.
257 The following elements are used in documentation:
259 <block subset="SUBSET" type="TYPE">XML_TEXT</block>
261 Create a block of text, similar in concept to a paragraph, but
262 is used to create divisions within the text. To some extent, a
263 <block/> is equivalent to the HTML <h2/> tag.
264 SUBSET should always be the value none .
266 TYPE specifies the heading and formatting to use. Recognized
268 types are:
269 behaviors Creates a section with the heading Operation .
271 note Creates a section with the heading Note: .
273 overrides Creates a section with the heading Note to Inheritors
275 .
276 usage Creates a section with the heading Usage .
278 <c>XML_TEXT</c>
280 Set text in a code-like font (similar to the HTML <tt/> ele‐
281 ment).
282 <code lang="LANGUAGE">TEXT</code>
284 Display multiple lines of text in a code-like font (similar to
285 the HTML <pre/> element). LANGUAGE is the language this code
286 block is for. For example, if LANGUAGE is C# , then TEXT will
287 get syntax highlighting for the C# language within the Mono Doc‐
288 umentation Browser.
289 <example>XML_TEXT</example>
291 Indicates an example that should be displayed specially. For
292 example:
293 <example>
294 <para>An introductory paragraph.</para>
295 <code lang="C#">
296 class Example {
297 public static void Main ()
298 {
299 System.Console.WriteLine ("Hello, World!");
300 }
301 }
302 </code>
303 </example>
304 <exception cref="CREF">XML_TEXT</exception>
306 Identifies an exception that can be thrown by the documented
307 member.
308 <exception/> is a top-level element, and should be nested
310 directly under the <Docs/> element.
311 CREF is the exception type that is thrown, while XML_TEXT con‐
313 tains the circumstances that would cause CREF to be thrown.
314 <exception cref="T:System.ArgumentNullException">
315 <paramref name="foo" /> was <see langword="null" />.
316 </exception>
317 <list>XML</list>
319 Create a list or table of items. <list/> makes use of nested
320 <item>XML</item> , <listheader>XML</listheader> ,
321 <term>XML_TEXT</term> , and <description>XML_TEXT</description>
322 elements.
323 Lists have the syntax:
325 <list type="bullet"> <!-- or type="number" -->
326 <item><term>Bullet 1</term></item>
327 <item><term>Bullet 2</term></item>
328 <item><term>Bullet 3</term></item>
329 </list>
330 Tables have the syntax:
332 <list type="table">
333 <listheader> <!-- listheader bolds this row -->
334 <term>Column 1</term>
335 <description>Column 2</description>
336 <description>Column 3</description>
337 </listheader>
338 <item>
339 <term>Item 1-A</term>
340 <description>Item 1-B</description>
341 <description>Item 1-C</description>
342 </item>
343 <item>
344 <term>Item 2-A</term>
345 <description>Item 2-B</description>
346 <description>Item 2-C</description>
347 </item>
348 </list>
349 <para>XML_TEXT</para>
351 Insert a paragraph of XML_TEXT
352 . This is for use within other tags, such as <example/> ,
353 <remarks/> , <returns/> , <term/> and <description/> (see
354 <list/> , above), and most other elements.
355 For example,
357 <para>This is a paragraph of text.</para>
358 <param name="NAME">XML_TEXT</param>
360 <param/> is a top-level element, and should be nested directly
361 under the <Docs/> element.
362 Describes the parameter NAME of the current constructor, method,
364 or property:
365 <param name="count">
366 A <see cref="T:System.Int32" /> containing the number
367 of widgets to process.
368 </param>
369 <paramref name="NAME" />
371 Indicates that NAME is a parameter.
372 This usually renders NAME as italic text, so it is frequently
374 (ab)used as an equivalent to the HTML <i/> element. See the
375 <exception/> documentation (above) for an example.
376 <permission cref="CREF">XML_TEXT</permission>
378 Documentes the security accessibility requirements of the cur‐
379 rent member.
380 <permission/> is a top-level element, and should be nested
382 directly under the <Docs/> element.
383 CREF is a type reference to the security permission required,
385 while XML_TEXT is a description of why the permission is
386 required.
387 <permission cref="T:System.Security.Permissions.FileIOPermission">
388 Requires permission for reading and writing files. See
389 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
390 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
391 </permission>
392 <remarks>XML_TEXT</remarks>
394 Contains detailed information about a member.
395 <remarks/> is a top-level element, and should be nested directly
397 under the <Docs/> element.
398 <remarks>Insert detailed information here.</remarks>
399 <returns>XML_TEXT</returns>
401 <remarks/> is a top-level element, and should be nested directly
403 under the <Docs/> element.
404 Describes the return value of a method:
406 <returns>
407 A <see cref="T:System.Boolean" /> specifying whether
408 or not the process can access
409 <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
410 </returns>
411 <see cref="CREF" />
413 Creates a link to the specified member within the current text:
414 <see cref="M:Some.Namespace.With.Type.Method" />
415 <seealso cref="CREF" />
417 <seealso/> is a top-level element, and should be nested directly
419 under the <Docs/> element.
420 Allows an entry to be generated for the See Also subclause. Use
422 <see/> to specify a link from within text.
423 <seealso cref="P:System.Exception.Message" />
424 <since version="VERSION" />
426 <since/> is a top-level element, and should be nested directly
428 under the <Docs/> element.
429 Permits specification of which version introduced the specified
431 type or member.
432 <since version="Gtk# 2.4" />
433 <summary>DESCRIPTION</summary>
435 <summary/> is a top-level element, and should be nested directly
437 under the <Docs/> element.
438 Provides a (brief!) overview about a type or type member.
440 This is usually displayed as part of a class declaration, and
442 should be a reasonably short description of the type/member.
443 Use <remarks/> for more detailed information.
444 <typeparam name="NAME">DESCRPITION</typeparam>
446 <typeparam/> is a top-level element, and should be nested
447 directly under the <Docs/> element.
448 This is used to describe type parameter for a generic type or
450 generic method.
451 NAME is the name of the type parameter, while DESCRIPTION con‐
453 tains a description of the parameter (what it's used for, what
454 restrictions it must meet, etc.).
455 <typeparam name="T">The type of the underlying collection</typeparam>
456 <typeparamref>
458 Used to indicate that a word is a type parameter, for use within
459 other text blocks (e.g. within <para/> ).
460 <para>If <typeparamref name="T" /> is a struct, then...</para>
461 <value>DESCRIPTION</value>
463 <value/> is a top-level element, and should be nested directly
464 under the <Docs/> element.
465 Allows a property to be described.
467 <value>
468 A <see cref="T:System.String" /> containing a widget name.
469 </value>
470
472 mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), mon‐
473 odocs2html(1)
474
476 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for
477 details.
478
480 Visit http://www.mono-project.com for details
481 monodocer(1)