diff options
-rw-r--r-- | doc/classlib-doc | 105 | ||||
-rw-r--r-- | web/classlib-doc | 105 |
2 files changed, 210 insertions, 0 deletions
diff --git a/doc/classlib-doc b/doc/classlib-doc new file mode 100644 index 00000000000..49735af98b1 --- /dev/null +++ b/doc/classlib-doc @@ -0,0 +1,105 @@ +* Class Library Documentation + +** 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 + + + *** 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. + +** 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 + +*** 2 January 2002 + + 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. + +** Get Involved + + Help us define Mono's documentation structure! Subscribe to + <a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a> + and wade right in.
\ No newline at end of file diff --git a/web/classlib-doc b/web/classlib-doc new file mode 100644 index 00000000000..49735af98b1 --- /dev/null +++ b/web/classlib-doc @@ -0,0 +1,105 @@ +* Class Library Documentation + +** 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 + + + *** 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. + +** 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 + +*** 2 January 2002 + + 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. + +** Get Involved + + Help us define Mono's documentation structure! Subscribe to + <a href="http://lists.ximian.com/mailman/listinfo/mono-docs-list">mono-docs-list</a> + and wade right in.
\ No newline at end of file |