** Summary
- <em>
- [This documentation is in progress. Comments to
- <a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>.]
- </em>
-
While using inline XML tags to document classes is certainly
convenient, properly verbose documentation quickly overwhelms
the code, making the source quite difficult to read. Furthermore,
multilingual documentation makes for significant additional text.
- With these considerations in mind, Mono will use external XML files
- for type documentation, rather than documenting the source inline.
-
- Several tools will be created for managing, verifying, generating,
- and updating class library documentation, including:
-
- <ul>
- <li><a href="#docstub">docstub</a></li>
- <li><a href="#docverify">docverify</a></li>
- <li><a href="#docconv">docconv</a></li>
- <li><a href="#docgen">docgen</a></li>
- <li><a href="#monodoc">monodoc</a></li>
- </ul>
-
-** XML Documentation Files and Formats
+ With these considerations in mind, Mono is using external XML files
+ for class documentation, rather than documenting the source
+ inline. The XML file format used is inspired by the XML format used
+ to document the ECMA APIs.
+ Several tools exist for managing, verifying, generating,
+ and updating class library documentation.
+
+ The documentation infrastructure is part of the `Monodoc'
+ module. Monodoc includes a graphical GUI browser and tools to
+ generate the initial stubbed XML document out of an assembly.
-*** Monodoc XML
- This XML is similar to the XML documentation described in the
- C# standard, with added tags for internationalization and a
- slightly different structure. Documentation and a DTD/Schema
- for Monodoc XML is forthcoming.
-
- Monodoc XML does not contain any definitive type information,
- and is only useful in conjunction with the Type definition for
- whatever is being documented.
-
- This XML could be generated by hand, by monostub, or by monodoc.
-
-*** Assembly XML
- This XML is generated by combining runtime type information for
- an Assembly with a collection of Monodoc XML files. The resultant
- XML (in the best of cases) contains both complete type and
- documentary information for each type in the assembly.
-
- This XML contains enough information to be transformed into
- user-accessible documentation. It is likely that scripts
- will be created to generate reference docs as HTML and other
- formats.
-
- Documentation and a DTD/Schema for Assembly XML is forthcoming.
-
+ Download `monodoc' to start producing documentation for your
+ application.
+
+ For instructions, read the monodoc/README file.
+
** Documentation Tools
-*** <a name="docstub">docstub</a>
- Given a type name and an assembly, generates stub Monodoc XML
- documentation for the type. Optionally, docstub can attempt to
- populate initial documentation from an XML file in the format
- published along with the ECMA standard.
-
-*** <a name="docverify">docverify</a>
- Given a Monodoc XML file and an assembly, verifies that the
- documentation matches the compiled type. Checks signatures,
- parameters, et cetera.
-
-*** <a name="docconv">docconv</a>
- Converts from Monodoc XML to the standard C# compiler-emitted
- XML format and vice versa.
-
-*** <a name="docgen">docgen</a>
- Given an assembly and a collection of Monodoc XML files, creates
- an Assembly XML file containing all documentation and type information
- available. This output is suitable for transforming into user
- documentation.
-
-*** <a name="monodoc">monodoc</a>
- A GUI tool for documentation and translation, this encapsulates
- the capabilities of docstub, docverify, docconv, and docgen in
- a friendly user interface. In addition, monodoc provides features
- to ease translation, such as side-by-side editing and coverage
- statistics.
-
-** Status and Roadmap
+*** <a name="monodoc">MonoDoc</a>
-*** 2 January 2002
+ The MonoDoc system offers both a GUI client as well as a <a
+ href="http://www.go-mono.com:8080">Web-based interface</a> to
+ the documentation.
- As I write the initial version of this document, very little has been
- implemented. Currently, there is a:
-
- <ul>
- <li>Preliminary version of the Monodoc XML format</li>
- <li>Preliminary version of the docstub utility</li>
- </ul>
-
- Here's hoping for frequent, productive updates.
+ The GUI edition uses <a
+ href="http://gtk-sharp.sf.net">Gtk#</a> and the Web edition
+ uses Mono's ASP.NET implementation.
+
+ <img src="images/Screenshot-Monodoc.png">
** Get Involved
- Help us define Mono's documentation structure! Subscribe to
+ Help us develop Mono's documentation tools! Subscribe to
<a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a>
and wade right in.
+
+ Monodoc today also supports a GUI-based collaborative editing
+ system. You can now edit the documentation from the MonoDoc
+ Browser and upload your contributions directly to the Mono site.
projects / mono.git / blobdiff