| blob | 8bbc34cb239284d9e71ff9bd8f078fcd93bde9cc |
1 .\"
2 .\" monodocer manual page.
3 .\" (C) 2006 Jonathan Pryor
4 .\" Author:
5 .\" Jonathan Pryor (jonpryor@vt.edu)
6 .\"
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .TH "monodocer" 1
12 .SH NAME
13 monodocer \- ECMA Documentation Format Support
14 .SH SYNOPSIS
15 .B monodocer
16 [OPTIONS]*
17 .SH OPTIONS
18 .TP
19 .I \-assembly:ASSEMBLY
20 .I ASSEMBLY
21 is a .NET assembly to generate documentation stubs for.
22 .Sp
23 Specify a file path or the name of a GAC'd assembly.
24 .TP
25 .I \-delete
26 Allow monodocer to delete members from documentation files.
27 The only members deleted are for members which are no longer present within
28 the assembly.
29 .Sp
30 If a type is no longer present, the documentation file is
31 .I not
32 deleted, but is instead
33 .I renamed
34 to have a
35 .B .remove
36 extension.
37 .TP
38 .I \-?, \-help
39 Show program argument information.
40 .TP
41 .I \-ignoremembers
42 Do not update members.
43 .Sp
44 This will add documentation stubs for added types, but will
45 .I not
46 add or remove documentation for any members of any type (including any added
47 types).
48 .TP
49 .I \-importslashdoc:FILE
50 .I FILE
51 is an XML file generated with the
52 .B /doc:FILE
53 C# compiler flag (e.g.
54 .I mcs -doc:foo.xml foo.cs
55 ). Import the member documentation contained within
56 .I FILE
57 into the documentation format used by monodoc.
58 .TP
59 .I \-name:NAME
60 .I NAME
61 is the name of the project this documentation is for.
62 .Sp
63 This sets the
64 .I /Overview/Title
65 element within the
66 .I index.xml
67 file created at the directory specified by
68 .I -path
69 \&.
70 This is used by some programs for title information (e.g.
71 .I monodocs2html
72 ).
73 .TP
74 .I \-namespace:NAMESPACE
75 Only update the types within the namespace
76 .I NAMESPACE
77 \&.
78 .TP
79 .I \-overrides
80 Include overridden methods in documentation.
81 .Sp
82 This normally isn't necessary, as the Mono Documentation Browser will provide a
83 link to the base type members anyway, as will
84 .I monodocs2html
85 if the base type is within the same assembly.
86 .TP
87 .I \-path:OUTPUT_DIR
88 .I OUTPUT_DIR
89 is the directory which will contain the new/updated documentation stubs.
90 .TP
91 .I \-pretty
92 Indent the XML files nicely.
93 .TP
94 .I \-since:SINCE
95 Create a <since/> element for added types and members with the value
96 .I SINCE
97 \&.
98 .Sp
99 For example, when given
100 .I -since:"Gtk# 2.4"
101 an element will be inserted into the
102 .I Docs
103 element for all added types and type members:
104 .nf
105 <since version="Gtk# 2.4" />
106 .fi
107 The Mono Documentation Browser and
108 .I monodocs2html
109 will use this element to specify in which version a member was added.
110 .TP
111 .I \-type:TYPE
112 Only create/update documentation for the type
113 .I TYPE
114 \&.
115 .TP
116 .I \-updateto:PATH
117 When updating documentation, write the updated documentation files into the
118 directory
119 .I PATH
120 \&.
121 .TP
122 .I \-V, \-version
123 Display version and licensing information.
124 .PP
125 .SH DESCRIPTION
126 \fBmonodocer\fR has been obsoleted by \fBmdoc\fR(1). See the
127 \fBmdoc-update\fR(1) man page.
128 .PP
129 .I monodocer
130 is a program that creates XML documentation stubs in the ECMA Documentation
131 Format. It does not rely on documentation found within the source code.
132 .PP
133 The advantages are:
134 .TP
135 .I *
136 .B Code readability.
137 Good documentation is frequently (a) verbose, and (b)
138 filled with examples. (For comparison, compare Microsoft .NET Framework
139 documentation, which is often a page or more of docs for each member, to
140 JavaDoc documentation, which can often be a sentence for each member.)
141 .Sp
142 Inserting good documentation into the source code can frequently bloat the
143 source file, as the documentation can be longer than the actual method that is
144 being documented.
145 .TP
146 .I *
147 .B Localization.
148 In-source documentation formats (such as
149 .B /doc
150 ) have no support for multiple human languages. If you need to support more
151 than one human language for documentation purposes,
152 .I monodocer
153 is useful as it permits each language to get its own directory, and
154 .I monodocer
155 can add types/members for each separate documentation directory.
156 .TP
157 .I *
158 .B Administration.
159 It's not unusual to have separate documentation and development teams. It's
160 also possible that the documentation team will have minimal experience with
161 the programming language being used. In such circumstances, inline
162 documentation is not desirable as the documentation team could inadvertantly
163 insert an error into the source code while updating the documentation.
164 Alternatively, you may not want the documentation team to have access to the
165 source code for security reasons.
166 .I monodocer
167 allows the documentation to be kept
168 .I completely
169 separate and distinct from the source code used to create the assembly.
170 .PP
171 To turn the
172 .I monodocer
173 documentation into something that can be consumed by the Mono
174 Documentation Browser (the desktop help browser, or the web interface
175 for it) it is necessary to compile the documentation into a packed
176 format. This is done with the mdassembler tool, for example, you
177 could use this toolchain like this:
178 .nf
180 $ monodocer -assembly:MyWidgets -path:generated_docs
181 $ mdassembler --ecma generated_docs -out:MyWidgets
183 .fi
184 The above would generate a MyWidgets.zip and a MyWidgets.tree that can
185 then be installed in the system. In addition to the two files (.zip
186 and .tree) you must provide a .sources file which describes where in
187 the help system the documentation should be hooked up, it is a very
188 simple XML file, like this:
189 .nf
191 <?xml version="1.0"?>
192 <monodoc>
193 <source provider="ecma" basefile="MyWidgets" path="classlib-gnome"/>
194 </monodoc>
196 .fi
197 The above configuration file describes that the documentation is in
198 ECMA format (the compiled version) that the base file name is
199 MyWidgets and that it should be hooked up in the "classlib-gnome" part
200 of the tree. If you want to look at the various nodes defined in the
201 documentation, you can look at monodoc.xml file which is typically
202 installed in /usr/lib/monodoc/monodoc.xml.
203 .PP
204 Once you have all of your files (.zip, .tree and .sources) you can
205 install them into the system with the following command:
206 .nf
208 $ cp MyWidgets.tree MyWidgets.zip MyWidgets.source `pkg-config monodoc --variable sourcesdir`
210 .fi
211 The above will copy the files into the directory that Monodoc has
212 registered (you might need root permissions to do this). The actual
213 directory is returned by the
214 .I pkg-config
215 invocation.
216 .SH STRING ID FORMAT
217 String IDs are used to refer to a type or member of a type. String IDs are
218 documented in ECMA-334 3rd Edition, Annex E.3.1. They consist of a
219 .I member type prefix
220 , the full type name (namespace + name, separated by '.'), possibly followed
221 by the member name and other information.
222 .PP
223 Member type prefixes:
224 .TP
225 .I "E:"
226 The String ID refers to an event. The event name follows the type name:
227 .I E:System.AppDomain.AssemblyLoad
228 .TP
229 .I "F:"
230 The String ID refers to a field. The field name follows the type name:
231 .I F:System.Runtime.InteropServices.DllImportAttribute.SetLastError
232 .TP
233 .I "M:"
234 Refers to a constructor or method. Constructors append
235 .I .ctor
236 to the type name, while methods append the method name (with an optional count
237 of the number of generic parameters).
238 .Sp
239 If the constructor or method take arguments, these are listed within
240 parenthesis after the constructor/method name:
241 .Sp
242 .I M:System.Object..ctor
243 ,
244 .I M:System.String..ctor(System.Char[])
245 ,
246 .I M:System.String.Concat(System.Object)
247 ,
248 .I M:System.Array.Sort``1(``0[])
249 ,
250 .I M:System.Collections.Generic.List`1..ctor
251 ,
252 .I M:System.Collections.Generic.List`1.Add(`0)
253 \&.
254 .TP
255 .I "N:"
256 Refers to a namespace, e.g.
257 .I N:System
258 .TP
259 .I "P:"
260 Refers to a property. If the property is an indexer or takes parameters,
261 the parameter types are appended to the property name and enclosed with
262 parenthesis:
263 .I P:System.String.Length
264 ,
265 .I P:System.String.Chars(System.Int32)
266 \&.
267 .TP
268 .I "T:"
269 The String ID refers to a type, with the number of generic types appended:
270 .I T:System.String
271 ,
272 .I T:System.Collections.Generic.List`1
273 .PP
274 To make matters more interesting, generic types & members have two
275 representations: the "unbound" representation (shown in examples above), in
276 which class names have the count of generic parameters appended to their name.
277 There is also a "bound" representation, in which the binding of generic
278 parameters is listed within '{' and '}'.
279 .PP
280 .B Unbound:
281 .I T:System.Collections.Generic.List`1
282 ,
283 .I T:System.Collections.Generic.Dictionary`2
284 \&.
285 .PP
286 .B Bound:
287 .I T:System.Collections.Generic.List{System.Int32}
288 .I T:System.Collections.Generic.Dictionary{System.String,System.Collections.Generic.List{System.Predicate{System.String}}}
289 \&.
290 .PP
291 As you can see, bound variants can be arbitrarily complex (just like
292 generics).
293 .PP
294 Furthermore, if a generic parameter is bound to the generic parameter of a
295 type or method, the "index" of the type/method's generic parameter is used
296 as the binding, so given
297 .nf
298 class FooType {
299 public static void Foo<T> (System.Predicate<T> predicate) {}
300 }
301 .fi
302 The String ID for this method is
303 .I M:FooType.Foo``1(System.Predicate{``0})
304 , as
305 .I ``0
306 is the 0th generic parameter index which is bound to
307 .I System.Predicate<T>
308 \&.
309 .SH DOCUMENTATION FORMAT
310 .I monodocer
311 generates documentation similar to the Ecma documentation format, as described
312 in ECMA-335 3rd Edition, Partition IV, Chapter 7.
313 .PP
314 The principal difference from the ECMA format is that each type gets its own
315 file, within a directory identical to the namespace of the type.
316 .PP
317 Most of the information within the documentation should
318 .I not
319 be edited. This includes the type name (
320 .I /Type/@FullName
321 ), implemented interfaces (
322 .I /Type/Interfaces
323 ), member information (
324 .I /Type/Members/Member/@MemberName
325 ,
326 .I /Type/Members/Member/MemberSignature
327 ,
328 .I /Type/Members/Member/MemberType
329 ,
330 .I /Type/Members/Member/Parameters
331 , etc.).
332 .PP
333 What
334 .I should
335 be modified are all elements with the text
336 .I To be added.
337 , which are present under the
338 .I //Docs
339 elements (e.g.
340 .I /Type/Docs
341 ,
342 .I /Type/Members/Member/Docs
343 ). The contents of the
344 .I Docs
345 element is
346 .I identical
347 in semantics and structure to the inline C# documentation format, consisting
348 of these elements (listed in ECMA-334 3rd Edition, Annex E, Section 2). The
349 following are used within the element descriptions:
350 .TP
351 .I CREF
352 Refers to a class (or member) reference, and is a string in the format
353 described above in the
354 .I STRING ID FORMAT
355 section.
356 .TP
357 .I TEXT
358 Non-XML text, and XML should not be nested.
359 .I
360 .TP
361 .I XML
362 Only XML elements should be nested (which indirectly may contain text), but
363 non-whitespace text should not be an immediate child node.
364 .TP
365 .I XML_TEXT
366 Free-form text and XML, so that other XML elements may be nested.
367 .PP
368 The following elements are used in documentation:
369 .TP
370 .I <block subset="SUBSET" type="TYPE">XML_TEXT</block>
371 Create a block of text, similar in concept to a paragraph, but is used to
372 create divisions within the text. To some extent, a <block/> is equivalent to
373 the HTML <h2/> tag.
374 .Sp
375 .I SUBSET
376 should always be the value
377 .I "none"
378 \&.
379 .Sp
380 .I TYPE
381 specifies the heading and formatting to use. Recognized types are:
382 .Sp
383 .I behaviors
384 Creates a section with the heading
385 .I Operation
386 \&.
387 .Sp
388 .I note
389 Creates a section with the heading
390 .I Note:
391 \&.
392 .Sp
393 .I overrides
394 Creates a section with the heading
395 .I Note to Inheritors
396 \&.
397 .Sp
398 .I usage
399 Creates a section with the heading
400 .I Usage
401 \&.
402 .TP
403 .I <c>XML_TEXT</c>
404 Set text in a code-like font (similar to the HTML <tt/> element).
405 .TP
406 .I <code lang="LANGUAGE">TEXT</code>
407 Display multiple lines of text in a code-like font (similar to the HTML <pre/>
408 element).
409 .I LANGUAGE
410 is the language this code block is for. For example, if
411 .I LANGUAGE
412 is
413 .B C#
414 , then
415 .I TEXT
416 will get syntax highlighting for the C# language within the Mono Documentation
417 Browser.
418 .TP
419 .I <example>XML_TEXT</example>
420 Indicates an example that should be displayed specially. For example:
421 .nf
422 <example>
423 <para>An introductory paragraph.</para>
424 <code lang="C#">
425 class Example {
426 public static void Main ()
427 {
428 System.Console.WriteLine ("Hello, World!");
429 }
430 }
431 </code>
432 </example>
433 .fi
434 .TP
435 .I <exception cref="CREF">XML_TEXT</exception>
436 Identifies an exception that can be thrown by the documented member.
437 .Sp
438 .I <exception/>
439 is a top-level element, and should be nested directly under the
440 .I <Docs/>
441 element.
442 .Sp
443 .I CREF
444 is the exception type that is thrown, while
445 .I XML_TEXT
446 contains the circumstances that would cause
447 .I CREF
448 to be thrown.
449 .nf
450 <exception cref="T:System.ArgumentNullException">
451 <paramref name="foo" /> was <see langword="null" />.
452 </exception>
453 .fi
454 .TP
455 .I <list>XML</list>
456 Create a list or table of items.
457 .I <list/>
458 makes use of nested
459 .I <item>XML</item>
460 ,
461 .I <listheader>XML</listheader>
462 ,
463 .I <term>XML_TEXT</term>
464 , and
465 .I <description>XML_TEXT</description>
466 elements.
467 .Sp
468 .I Lists
469 have the syntax:
470 .nf
471 <list type="bullet"> <!-- or type="number" -->
472 <item><term>Bullet 1</term></item>
473 <item><term>Bullet 2</term></item>
474 <item><term>Bullet 3</term></item>
475 </list>
476 .fi
477 .Sp
478 .I Tables
479 have the syntax:
480 .nf
481 <list type="table">
482 <listheader> <!-- listheader bolds this row -->
483 <term>Column 1</term>
484 <description>Column 2</description>
485 <description>Column 3</description>
486 </listheader>
487 <item>
488 <term>Item 1-A</term>
489 <description>Item 1-B</description>
490 <description>Item 1-C</description>
491 </item>
492 <item>
493 <term>Item 2-A</term>
494 <description>Item 2-B</description>
495 <description>Item 2-C</description>
496 </item>
497 </list>
498 .fi
499 .TP
500 .I <para>XML_TEXT</para>
501 Insert a paragraph of
502 .I XML_TEXT
503 .
504 This is for use within other tags, such as
505 .I <example/>
506 ,
507 .I <remarks/>
508 ,
509 .I <returns/>
510 ,
511 .I <term/>
512 and
513 .I <description/>
514 (see
515 .I <list/>
516 , above), and most other elements.
517 .Sp
518 For example,
519 .nf
520 <para>This is a paragraph of text.</para>
521 .fi
522 .TP
523 .I <param name="NAME">XML_TEXT</param>
524 .I <param/>
525 is a top-level element, and should be nested directly under the
526 .I <Docs/>
527 element.
528 .Sp
529 Describes the parameter
530 .I NAME
531 of the current constructor, method, or property:
532 .nf
533 <param name="count">
534 A <see cref="T:System.Int32" /> containing the number
535 of widgets to process.
536 </param>
537 .fi
538 .TP
539 .I <paramref name="NAME" />
540 Indicates that
541 .I NAME
542 is a parameter.
543 .Sp
544 This usually renders
545 .I NAME
546 as italic text, so it is frequently (ab)used as an equivalent to the
547 HTML <i/> element. See the
548 .I <exception/>
549 documentation (above) for an example.
550 .TP
551 .I <permission cref="CREF">XML_TEXT</permission>
552 Documentes the security accessibility requirements of the current member.
553 .Sp
554 .I <permission/>
555 is a top-level element, and should be nested directly under the
556 .I <Docs/>
557 element.
558 .Sp
559 .I CREF
560 is a type reference to the security permission required, while
561 .I XML_TEXT
562 is a description of why the permission is required.
563 .nf
564 <permission cref="T:System.Security.Permissions.FileIOPermission">
565 Requires permission for reading and writing files. See
566 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Read" />,
567 <see cref="F:System.Security.Permissions.FileIOPermissionAccess.Write" />.
568 </permission>
569 .fi
570 .TP
571 .I <remarks>XML_TEXT</remarks>
572 Contains detailed information about a member.
573 .Sp
574 .I <remarks/>
575 is a top-level element, and should be nested directly under the
576 .I <Docs/>
577 element.
578 .nf
579 <remarks>Insert detailed information here.</remarks>
580 .fi
581 .TP
582 .I <returns>XML_TEXT</returns>
583 .Sp
584 .I <remarks/>
585 is a top-level element, and should be nested directly under the
586 .I <Docs/>
587 element.
588 .Sp
589 Describes the return value of a method:
590 .nf
591 <returns>
592 A <see cref="T:System.Boolean" /> specifying whether
593 or not the process can access
594 <see cref="P:Mono.Unix.UnixFileSystemInfo.FullName" />.
595 </returns>
596 .fi
597 .TP
598 .I <see cref="CREF" />
599 Creates a link to the specified member within the current text:
600 .nf
601 <see cref="M:Some.Namespace.With.Type.Method" />
602 .fi
603 .TP
604 .I <seealso cref="CREF" />
605 .Sp
606 .I <seealso/>
607 is a top-level element, and should be nested directly under the
608 .I <Docs/>
609 element.
610 .Sp
611 Allows an entry to be generated for the
612 .I See Also
613 subclause. Use
614 .I <see/>
615 to specify a link from within text.
616 .nf
617 <seealso cref="P:System.Exception.Message" />
618 .fi
619 .TP
620 .I <since version="VERSION" />
621 .Sp
622 .I <since/>
623 is a top-level element, and should be nested directly under the
624 .I <Docs/>
625 element.
626 .Sp
627 Permits specification of which version introduced the specified type or
628 member.
629 .nf
630 <since version="Gtk# 2.4" />
631 .fi
632 .TP
633 .I <summary>DESCRIPTION</summary>
634 .Sp
635 .I <summary/>
636 is a top-level element, and should be nested directly under the
637 .I <Docs/>
638 element.
639 .Sp
640 Provides a (brief!) overview about a type or type member.
641 .Sp
642 This is usually displayed as part of a class declaration, and should be a
643 reasonably short description of the type/member. Use
644 .I <remarks/>
645 for more detailed information.
646 .TP
647 .I <typeparam name="NAME">DESCRPITION</typeparam>
648 .I <typeparam/>
649 is a top-level element, and should be nested directly under the
650 .I <Docs/>
651 element.
652 .Sp
653 This is used to describe type parameter for a generic type or generic method.
654 .Sp
655 .I NAME
656 is the name of the type parameter, while
657 .I DESCRIPTION
658 contains a description of the parameter (what it's used for, what restrictions
659 it must meet, etc.).
660 .nf
661 <typeparam name="T">The type of the underlying collection</typeparam>
662 .fi
663 .TP
664 .I <typeparamref>
665 Used to indicate that a word is a type parameter, for use within other text
666 blocks (e.g. within
667 .I <para/>
668 ).
669 .nf
670 <para>If <typeparamref name="T" /> is a struct, then...</para>
671 .fi
672 .TP
673 .I <value>DESCRIPTION</value>
674 .I <value/>
675 is a top-level element, and should be nested directly under the
676 .I <Docs/>
677 element.
678 .Sp
679 Allows a property to be described.
680 .nf
681 <value>
682 A <see cref="T:System.String" /> containing a widget name.
683 </value>
684 .fi
685 .PP
686 .SH SEE ALSO
687 mdassembler(1), mdcs2ecma(1), mdnormalizer(1), mdvalidator(1), monodocs2html(1)
688 .SH MAILING LISTS
689 .TP
690 Visit http://lists.ximian.com/mailman/listinfo/mono-docs-list for details.
691 .SH WEB SITE
692 Visit http://www.mono-project.com for details