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 is a program that creates XML documentation stubs in the ECMA
88 Documentation Format. It does not rely on documentation found within
89 the source code.
90 The advantages are:
92 * Code readability. Good documentation is frequently (a) verbose,
94 and (b) filled with examples. (For comparison, compare Micro‐
95 soft .NET Framework documentation, which is often a page or more
96 of docs for each member, to JavaDoc documentation, which can
97 often be a sentence for each member.)
98 Inserting good documentation into the source code can frequently
100 bloat the source file, as the documentation can be longer than
101 the actual method that is being documented.
102 * Localization. In-source documentation formats (such as /doc )
104 have no support for multiple human languages. If you need to
105 support more than one human language for documentation purposes,
106 monodocer is useful as it permits each language to get its own
107 directory, and monodocer can add types/members for each separate
108 documentation directory.
109 * Administration. It's not unusual to have separate documentation
111 and development teams. It's also possible that the documenta‐
112 tion team will have minimal experience with the programming lan‐
113 guage being used. In such circumstances, inline documentation
114 is not desirable as the documentation team could inadvertantly
115 insert an error into the source code while updating the documen‐
116 tation. Alternatively, you may not want the documentation team
117 to have access to the source code for security reasons. mon‐
118 odocer allows the documentation to be kept completely separate
119 and distinct from the source code used to create the assembly.
120
122 String IDs are used to refer to a type or member of a type. String IDs
123 are documented in ECMA-334 3rd Edition, Annex E.3.1. They consist of a
124 member type prefix , the full type name (namespace + name, separated by
125 '.'), possibly followed by the member name and other information.
126 Member type prefixes:
128 E: The String ID refers to an event. The event name follows the
130 type name: E:System.AppDomain.AssemblyLoad
131 F: The String ID refers to a field. The field name follows the
133 type name: F:System.Runtime.InteropServices.DllImportAt‐
134 tribute.SetLastError
135 M: Refers to a constructor or method. Constructors append .ctor to
137 the type name, while methods append the method name (with an
138 optional count of the number of generic parameters).
139 If the constructor or method take arguments, these are listed
141 within paranthesis after the constructor/method name:
142 M:System.Object..ctor , M:System.String..ctor(System.Char[]) ,
144 M:System.String.Concat(System.Object) , M:Sys‐
145 tem.Array.Sort``1(``0[]) , M:System.Collec‐
146 tions.Generic.List`1..ctor , M:System.Collec‐
147 tions.Generic.List`1.Add(`0) .
148 N: Refers to a namespace, e.g. N:System
150 P: Refers to a property. If the property is an indexer or takes
152 parameters, the parameter types are appended to the property
153 name and enclosed with paranthesis: P:System.String.Length ,
154 P:System.String.Chars(System.Int32) .
155 T: The String ID refers to a type, with the number of generic types
157 appended: T:System.String , T:System.Collections.Generic.List`1
158 To make matters more interesting, generic types & members have two rep‐
160 resentations: the "unbound" representation (shown in examples above),
161 in which class names have the count of generic parameters appended to
162 their name. There is also a "bound" representation, in which the bind‐
163 ing of generic parameters is listed within '{' and '}'.
164 Unbound: T:System.Collections.Generic.List`1 , T:System.Collec‐
166 tions.Generic.Dictionary`2 .
167 Bound: T:System.Collections.Generic.List{System.Int32} T:System.Collec‐
169 tions.Generic.Dictionary{System.String,System.Collec‐
170 tions.Generic.List{System.Predicate{System.String}}} .
171 As you can see, bound variants can be arbitrarily complex (just like
173 generics).
174 Furthermore, if a generic parameter is bound to the generic parameter
176 of a type or method, the "index" of the type/method's generic parameter
177 is used as the binding, so given
178 class FooType {
179 public static void Foo<T> (System.Predicate<T> predicate) {}
180 }
181 The String ID for this method is M:FooType.Foo``1(System.Predi‐
182 cate{``0}) , as ``0 is the 0th generic parameter index which is bound
183 to System.Predicate<T> .
184
186 monodocer generates documentation similar to the Ecma documentation
187 format, as described in ECMA-335 3rd Edition, Partition IV, Chapter 7.
188 The principal difference from the ECMA format is that each type gets
190 its own file, within a directory identical to the namespace of the
191 type.
192 Most of the information within the documentation should not be edited.
194 This includes the type name ( /Type/@FullName ), implemented interfaces
195 ( /Type/Interfaces ), member information ( /Type/Members/Member/@Mem‐
196 berName , /Type/Members/Member/MemberSignature , /Type/Members/Mem‐
197 ber/MemberType , /Type/Members/Member/Parameters , etc.).
198 What should be modified are all elements with the text To be added. ,
200 which are present under the //Docs elements (e.g. /Type/Docs ,
201 /Type/Members/Member/Docs ). The contents of the Docs element is iden‐
202 tical in semantics and structure to the inline C# documentation format,
203 consisting of these elements (listed in ECMA-334 3rd Edition, Annex E,
204 Section 2). The following are used within the element descriptions:
205 CREF Refers to a class (or member) reference, and is a string in the
207 format described above in the STRING ID FORMAT section.
208 TEXT Non-XML text, and XML should not be nested.
210 XML Only XML elements should be nested (which indirectly may contain
212 text), but non-whitespace text should not be an immediate child
213 node.
214 XML_TEXT
216 Free-form text and XML, so that other XML elements may be
217 nested.
218 The following elements are used in documentation:
220 <block subset="SUBSET" type="TYPE">XML_TEXT</block>
222 Create a block of text, similar in concept to a paragraph, but
223 is used to create divisions within the text. To some extent, a
224 <block/> is equivalent to the HTML <h2/> tag.
225 SUBSET should always be the value none .
227 TYPE specifies the heading and formatting to use. Recognized
229 types are:
230 behaviors Creates a section with the heading Operation .
232 note Creates a section with the heading Note: .
234 overrides Creates a section with the heading Note to Inheritors
236 .
237 usage Creates a section with the heading Usage .
239 <c>XML_TEXT</c>
241 Set text in a code-like font (similar to the HTML <tt/> ele‐
242 ment).
243 <code lang="LANGUAGE">TEXT</code>
245 Display multiple lines of text in a code-like font (similar to
246 the HTML <pre/> element). LANGUAGE is the language this code
247 block is for. For example, if LANGUAGE is C# , then TEXT will
248 get syntax highlighting for the C# language within the Mono Doc‐
249 umentation Browser.
250 <example>XML_TEXT</example>
252 Indicates an example that should be displayed specially. For
253 example:
254 <example>
255 <para>An introductory paragraph.</para>
256 <code lang="C#">
257 class Example {
258 public static void Main ()
259 {
260 System.Console.WriteLine ("Hello, World!");
261 }
262 }
263 </code>
264 </example>
265 <exception cref="CREF">XML_TEXT</exception>
267 Identifies an exception that can be thrown by the documented
268 member.
269 <exception/> is a top-level element, and should be nested
271 directly under the <Docs/> element.
272 CREF is the exception type that is thrown, while XML_TEXT con‐
274 tains the circumstances that would cause CREF to be thrown.
275 <exception cref="T:System.ArgumentNullException">
276 <paramref name="foo" /> was <see langword="null" />.
277 </exception>
278 <list>XML</list>
280 Create a list or table of items. <list/> makes use of nested
281 <item>XML</item> , <listheader>XML</listheader> ,
282 <term>XML_TEXT</term> , and <description>XML_TEXT</description>
283 elements.
284 Lists have the syntax:
286 <list type="bullet"> <!-- or type="number" -->
287 <item><term>Bullet 1</term></item>
288 <item><term>Bullet 2</term></item>
289 <item><term>Bullet 3</term></item>
290 </list>
291 Tables have the syntax:
293 <list type="table">
294 <listheader> <!-- listheader bolds this row -->
295 <term>Column 1</term>
296 <description>Column 2</description>
297 <description>Column 3</description>
298 </listheader>
299 <item>
300 <term>Item 1-A</term>
301 <description>Item 1-B</description>
302 <description>Item 1-C</description>
303 </item>
304 <item>
305 <term>Item 2-A</term>
306 <description>Item 2-B</description>
307 <description>Item 2-C</description>
308 </item>
309 </list>
310 <para>XML_TEXT</para>
312 Insert a paragraph of XML_TEXT
313 . This is for use within other tags, such as <example/> ,
314 <remarks/> , <returns/> , <term/> and <description/> (see
315 <list/> , above), and most other elements.
316 For example,
318 <para>This is a paragraph of text.</para>
319 <param name="NAME">XML_TEXT</param>
321 <param/> is a top-level element, and should be nested directly
322 under the <Docs/> element.
323 Describes the parameter NAME of the current constructor, method,
325 or property:
326 <param name="count">
327 A <see cref="T:System.Int32" /> containing the number
328 of widgets to process.
329 </param>
330 <paramref name="NAME" />
332 Indicates that NAME is a parameter.
333 This usually renders NAME as italic text, so it is frequently
335 (ab)used as an equivalent to the HTML <i/> element. See the
336 <exception/> documentation (above) for an example.
337 <permission cref="CREF">XML_TEXT</permission>
339 Documentes the security accessibility requirements of the cur‐
340 rent member.
341 <permission/> is a top-level element, and should be nested
343 directly under the <Docs/> element.
344 CREF is a type reference to the security permission required,
346 while XML_TEXT is a description of why the permission is
347 required.
348 <permission cref="T:System.Security.Permissions.FileIOPermission">
349 Requires permission for reading and writing files. See
350 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
351 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
352 </permission>
353 <remarks>XML_TEXT</remarks>
355 Contains detailed information about a member.
356 <remarks/> is a top-level element, and should be nested directly
358 under the <Docs/> element.
359 <remarks>Insert detailed information here.</remarks>
360 <returns>XML_TEXT</returns>
362 <remarks/> is a top-level element, and should be nested directly
364 under the <Docs/> element.
365 Describes the return value of a method:
367 <returns>
368 A <see cref="T:System.Boolean" /> specifying whether
369 or not the process can access
370 <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
371 </returns>
372 <see cref="CREF" />
374 Creates a link to the specified member within the current text:
375 <see cref="M:Some.Namespace.With.Type.Method" />
376 <seealso cref="CREF" />
378 <seealso/> is a top-level element, and should be nested directly
380 under the <Docs/> element.
381 Allows an entry to be generated for the See Also subclause. Use
383 <see/> to specify a link from within text.
384 <seealso cref="P:System.Exception.Message" />
385 <since version="VERSION" />
387 <since/> is a top-level element, and should be nested directly
389 under the <Docs/> element.
390 Permits specification of which version introduced the specified
392 type or member.
393 <since version="Gtk# 2.4" />
394 <summary>DESCRIPTION</summary>
396 <summary/> is a top-level element, and should be nested directly
398 under the <Docs/> element.
399 Provides a (brief!) overview about a type or type member.
401 This is usually displayed as part of a class declaration, and
403 should be a reasonably short description of the type/member.
404 Use <remarks/> for more detailed information.
405 <typeparam name="NAME">DESCRPITION</typeparam>
407 <typeparam/> is a top-level element, and should be nested
408 directly under the <Docs/> element.
409 This is used to describe type parameter for a generic type or
411 generic method.
412 NAME is the name of the type parameter, while DESCRIPTION con‐
414 tains a description of the parameter (what it's used for, what
415 restrictions it must meet, etc.).
416 <typeparam name="T">The type of the underlying collection</typeparam>
417 <typeparamref>
419 Used to indicate that a word is a type parameter, for use within
420 other text blocks (e.g. within <para/> ).
421 <para>If <typeparamref name="T" /> is a struct, then...</para>
422 <value>DESCRIPTION</value>
424 <value/> is a top-level element, and should be nested directly
425 under the <Docs/> element.
426 Allows a property to be described.
428 <value>
429 A <see cref="T:System.String" /> containing a widget name.
430 </value>
431
433 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for
434 details.
435
437 Visit http://www.mono-project.com for details
438 monodocer(1)