1 * Class Library Documentation
5 While using inline XML tags to document classes is certainly
6 convenient, properly verbose documentation quickly overwhelms
7 the code, making the source quite difficult to read. Furthermore,
8 multilingual documentation makes for significant additional text.
10 With these considerations in mind, Mono will use external XML files
11 for type documentation, rather than documenting the source inline.
13 Several tools will be created for managing, verifying, generating,
14 and updating class library documentation, including:
17 <li><a href="#docstub">docstub</a></li>
18 <li><a href="#docverify">docverify</a></li>
19 <li><a href="#docconv">docconv</a></li>
20 <li><a href="#docgen">docgen</a></li>
21 <li><a href="#monodoc">monodoc</a></li>
24 ** XML Documentation Files and Formats
28 This XML is similar to the XML documentation described in the
29 C# standard, with added tags for internationalization and a
30 slightly different structure. Documentation and a DTD/Schema
31 for Monodoc XML is forthcoming.
33 Monodoc XML does not contain any definitive type information,
34 and is only useful in conjunction with the Type definition for
35 whatever is being documented.
37 This XML could be generated by hand, by monostub, or by monodoc.
40 This XML is generated by combining runtime type information for
41 an Assembly with a collection of Monodoc XML files. The resultant
42 XML (in the best of cases) contains both complete type and
43 documentary information for each type in the assembly.
45 This XML contains enough information to be transformed into
46 user-accessible documentation. It is likely that scripts
47 will be created to generate reference docs as HTML and other
50 Documentation and a DTD/Schema for Assembly XML is forthcoming.
52 ** Documentation Tools
54 *** <a name="docstub">docstub</a>
55 Given a type name and an assembly, generates stub Monodoc XML
56 documentation for the type. Optionally, docstub can attempt to
57 populate initial documentation from an XML file in the format
58 published along with the ECMA standard.
60 *** <a name="docverify">docverify</a>
61 Given a Monodoc XML file and an assembly, verifies that the
62 documentation matches the compiled type. Checks signatures,
63 parameters, et cetera.
65 *** <a name="docconv">docconv</a>
66 Converts from Monodoc XML to the standard C# compiler-emitted
67 XML format and vice versa.
69 *** <a name="docgen">docgen</a>
70 Given an assembly and a collection of Monodoc XML files, creates
71 an Assembly XML file containing all documentation and type information
72 available. This output is suitable for transforming into user
75 *** <a name="monodoc">monodoc</a>
76 A GUI tool for documentation and translation, this encapsulates
77 the capabilities of docstub, docverify, docconv, and docgen in
78 a friendly user interface. In addition, monodoc provides features
79 to ease translation, such as side-by-side editing and coverage
86 As I write the initial version of this document, very little has been
87 implemented. Currently, there is a:
90 <li>Preliminary version of the Monodoc XML format</li>
91 <li>Preliminary version of the docstub utility</li>
94 Here's hoping for frequent, productive updates.
98 Help us define Mono's documentation structure! Subscribe to
99 <a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>