diff options
| -rw-r--r-- | doc/classlib-doc | 44 | ||||
| -rw-r--r-- | doc/documentation | 162 | ||||
| -rw-r--r-- | doc/index | 13 | ||||
| -rw-r--r-- | web/classlib-doc | 44 | ||||
| -rw-r--r-- | web/documentation | 162 | ||||
| -rw-r--r-- | web/index | 13 |
6 files changed, 366 insertions, 72 deletions
diff --git a/doc/classlib-doc b/doc/classlib-doc index 19f92d6dfcf..b002b8efd55 100644 --- a/doc/classlib-doc +++ b/doc/classlib-doc @@ -8,53 +8,31 @@ 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. - + for type 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 will be created for managing, verifying, generating, and updating class library documentation, including: <ul> - <li><a href="#monodoc">MonoDoc - A graphical documentation editor and viewer.</a></li> - <li><a href="#mkmaster">MkMaster - A command line tool to feed stub information to MonoDoc.</a></li> - <li><a href="#aspnet">An ASP.NET documentation editor.</a></li> - <li><a href="#xsltool">An xsl tool to convert monodoc xml to html documentation.</a></li> + <li><a href="#monodoc">monodoc - A graphical documentation viewer.</a></li> + <li>xmllint: a tool used to validate a proper XML document. </ul> -** XML Documentation Files and Formats - - -*** Monodoc XML - This XML is Mono's documentation format. Documentation and a DTD/Schema - for Monodoc XML is located in cvs and can be found <a href="http://go-mono.org/monodoc.dtd">here</a>. - - This XML could be generated by MonoDoc or the ASP.NET client. + You can download the tools to document Mono from the CVS + repository from module `monodoc'. - More about the XML format <a href="http://go-mono.org/monodoc-xml.html">here</a>. ** Documentation Tools *** <a name="monodoc">MonoDoc</a> - A graphical documentation editor and viewer. Currently, MonoDoc - consists of a Qt# application and is in heavy development. -*** <a name="mkmaster">MkMaster</a> - This tool creates the Master.xml file that MonoDoc uses as a reference - for documentation generation. This is a reflection engine that is used - to gather metadata from assemblies and create an xml representation. - -*** <a name="aspnet">ASP.NET</a> - This tool is planned. - -*** <a name="xsltool">An XSL converter</a> - This tool is planned. If someone wants to step forward and adopt this - project, it would be very helpful ;) + A graphical documentation viewer written in Gtk#. In the + future we will have an ASP.NET front-end to present the + documentation on the web as well. ** Status and Roadmap -*** 16, September 2002 - -A preliminary version of MonoDoc is in Mono's cvs. It is under heavy development. -Once this is complete we will start documenting the API! - ** Get Involved Help us develop Mono's documentation tools! Subscribe to diff --git a/doc/documentation b/doc/documentation index 4ed2e6a6639..c78f9eaf080 100644 --- a/doc/documentation +++ b/doc/documentation @@ -14,13 +14,16 @@ <ul> * The development tools (compilers, assembler tools, - language reference, design time features). + language reference, design time features): these + live in the `monodoc' CVS module. * Frequently Asked Question compilations. * HOWTO documents. - * The Class Libraries + * The Class Libraries (Both the original .NET class + libraries as well as the class libraries produced by + the project). * Tutorials on Mono and the specifics of running it. @@ -29,11 +32,164 @@ </ul> -** Class Library documentation +* Class Library documentation We are moving to a new setup for documenting the class libraries, and you can read about it <a href="classlib-doc.html">here</a>. + There are two classes of documentation: free documentation for + existing .NET classes and documentation for the classes that + we have developed on top of .NET. + + There is a large body of documentation that came from the ECMA + standarization effort that has been checked into CVS. It does + not contain everything Mono and .NET have, so they need to be + updated and augmented. + +** Gtk# documentation + + We also have a large body of class libraries that are specific + to Mono, for example the documentation for Gtk#. + + We have checked in stub documentation for Gtk# into the CVS + repository (on gtk-sharp/doc) and we need volunteers to help + populate the documentation for it. Since Gtk# is a wrapper + for Gtk, plenty of documentation exists in the <a + href="http://developer.gnome.org/doc/API/2.0/">Gnome developer + site</a>. + + To get started: + + You need to download Gtk# from the CVS repository. The module + name is `gtk-sharp'. You can obtain a copy from both the CVS + repository or the anonymous CVS repository. + + To pull your copy type: + + cvs co gtk-sharp + + Documentation lives in gtk-sharp/doc/en. The "en" indicates the + English language, the first one we are targeting. We can later + do translations, but for now we are focusing on a single + language. + + In that directory you will find the documentation organized by + namespaces. One directory per namespace. In the directories + you will find one XML file per class that needs to be + documented. The mission is to fill in the data with useful + information. Feel free to grab liberally information from the + Gtk documentation from: + + <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a> + + Of course, the API does not apply directly. It only applies at + a foundational level, so you can not really just copy and + paste. Summaries, and remarks sections can probably be lifted + with little or no effort. + + Gtk# uses properties to represent get/set operations in the C + API, so you can also use some bits from there. + + Most of the documentation contains already place holders for + text, we use the internationally approved phrase for this + purpose, `To be added'. So the quest is to remove all of the + "To be added" strings with information with resembles as closely + as possible the toolkit reality. + +*** The pieces to be filled. + + Summaries are one or two line descriptions of the element + (class, struct, interface, method, field, event, delegate), and + its used to render summary pages. So it has to be short. + + The "remarks" section is used to describe in detail the element. + +**** Tags. + + As you document Gtk# you will have a number of tags that you can + use inside the summary and remarks sections, these are: + + <para> </para> + Used to separate paragraphs. + + <paramref name="param_name"/> + Used to reference a formal parameter to a function. + + <see cref="T:SomeTypeName"/> + Use this to reference a type, this will include an hyper + link to the page for type SomeTypeName. + + For example, to reference "System.Enum", do: + + <see cref="T:System.Enum"/> + + <see cref="P:SomeTypeName.Property"/> + Use this to reference a property, this will include an hyper + link to the page for the property `Property' of type `SomeTypeName'. + + For example, to reference the BaseType property in System.Type, do: + + <see cref="P:System.Type.BaseType"/> + + <see cref="M:SomeTypeName.Method(type,type)"/> + Use this to reference a method, this will include an hyper + link to the page for the method `Method' of type `SomeTypeName'. + + For example, to reference the ToString method in System.Object, do: + + <see cref="M:System.Object.ToString()"/> + + <see langword="keywrod"/> + Use this to link to a keyword in the C# language, for + example to link to `true', do: + + <see langword="true"/> + + <example> ... </example> + + Use example to insert an example. The example can + contain explanatory text and code. + + <code lang="C#">.. </code> + + Use this to provide a sample C# program, typically used + within the <example> tags. + + When providing examples, try to provide a full example, + we would like to be able to have a button to compile and + run samples embedded into the documentation, or pop up + an editor to let the user play with the sample. + + You can link to an example like this: + + <code lang="C#" source="file.cs"> </code> + + <item> + + <list type="bullet"> </list> + + Use this to create lists. Lists contains <item> + elements + + <list type="table"> </lits> + <listheader> + <term>YOUR FIRST COLUMN</term> + <description>YOUR DESCRIPTION</description> + </listheader> + + For two-column tables. Inside use: + + <item> + <term>First</term> + <description>First descritpion</description> + </item> + <item> + <term>Second</term> + <description>Second descirption</description> + </item> + +** Words of warning. + A few words of warning and advice for class documentors: A well-documented API can ease hours of frustration; as Mono diff --git a/doc/index b/doc/index index 2294b1f2850..cabd7564f4b 100644 --- a/doc/index +++ b/doc/index @@ -102,6 +102,19 @@ </tr> </table> +@item Feb 18th, 2003: Volunteers to document Gtk# + + With the availability of a documentation browser, we are + looking for volunteers to help us complete the documentation + of the Gtk# binding for Mono. + + Experience with Gtk is useful, but not mandatory. We have + checked in stubs, and we have instructions, and resources to + how to complete this process <a + href="documentation.html">here</a>. Mail the <a + href="mailto:mono-docs-list@ximian.com">mono-docs-list@ximian.com</a> + for further discussion. + @item Feb 14th, 2003: OpenGL# bindings for Mono; Mono Basic updates. Mark Crichton has completed his OpenGL/GLUT bindings for diff --git a/web/classlib-doc b/web/classlib-doc index 19f92d6dfcf..b002b8efd55 100644 --- a/web/classlib-doc +++ b/web/classlib-doc @@ -8,53 +8,31 @@ 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. - + for type 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 will be created for managing, verifying, generating, and updating class library documentation, including: <ul> - <li><a href="#monodoc">MonoDoc - A graphical documentation editor and viewer.</a></li> - <li><a href="#mkmaster">MkMaster - A command line tool to feed stub information to MonoDoc.</a></li> - <li><a href="#aspnet">An ASP.NET documentation editor.</a></li> - <li><a href="#xsltool">An xsl tool to convert monodoc xml to html documentation.</a></li> + <li><a href="#monodoc">monodoc - A graphical documentation viewer.</a></li> + <li>xmllint: a tool used to validate a proper XML document. </ul> -** XML Documentation Files and Formats - - -*** Monodoc XML - This XML is Mono's documentation format. Documentation and a DTD/Schema - for Monodoc XML is located in cvs and can be found <a href="http://go-mono.org/monodoc.dtd">here</a>. - - This XML could be generated by MonoDoc or the ASP.NET client. + You can download the tools to document Mono from the CVS + repository from module `monodoc'. - More about the XML format <a href="http://go-mono.org/monodoc-xml.html">here</a>. ** Documentation Tools *** <a name="monodoc">MonoDoc</a> - A graphical documentation editor and viewer. Currently, MonoDoc - consists of a Qt# application and is in heavy development. -*** <a name="mkmaster">MkMaster</a> - This tool creates the Master.xml file that MonoDoc uses as a reference - for documentation generation. This is a reflection engine that is used - to gather metadata from assemblies and create an xml representation. - -*** <a name="aspnet">ASP.NET</a> - This tool is planned. - -*** <a name="xsltool">An XSL converter</a> - This tool is planned. If someone wants to step forward and adopt this - project, it would be very helpful ;) + A graphical documentation viewer written in Gtk#. In the + future we will have an ASP.NET front-end to present the + documentation on the web as well. ** Status and Roadmap -*** 16, September 2002 - -A preliminary version of MonoDoc is in Mono's cvs. It is under heavy development. -Once this is complete we will start documenting the API! - ** Get Involved Help us develop Mono's documentation tools! Subscribe to diff --git a/web/documentation b/web/documentation index 4ed2e6a6639..c78f9eaf080 100644 --- a/web/documentation +++ b/web/documentation @@ -14,13 +14,16 @@ <ul> * The development tools (compilers, assembler tools, - language reference, design time features). + language reference, design time features): these + live in the `monodoc' CVS module. * Frequently Asked Question compilations. * HOWTO documents. - * The Class Libraries + * The Class Libraries (Both the original .NET class + libraries as well as the class libraries produced by + the project). * Tutorials on Mono and the specifics of running it. @@ -29,11 +32,164 @@ </ul> -** Class Library documentation +* Class Library documentation We are moving to a new setup for documenting the class libraries, and you can read about it <a href="classlib-doc.html">here</a>. + There are two classes of documentation: free documentation for + existing .NET classes and documentation for the classes that + we have developed on top of .NET. + + There is a large body of documentation that came from the ECMA + standarization effort that has been checked into CVS. It does + not contain everything Mono and .NET have, so they need to be + updated and augmented. + +** Gtk# documentation + + We also have a large body of class libraries that are specific + to Mono, for example the documentation for Gtk#. + + We have checked in stub documentation for Gtk# into the CVS + repository (on gtk-sharp/doc) and we need volunteers to help + populate the documentation for it. Since Gtk# is a wrapper + for Gtk, plenty of documentation exists in the <a + href="http://developer.gnome.org/doc/API/2.0/">Gnome developer + site</a>. + + To get started: + + You need to download Gtk# from the CVS repository. The module + name is `gtk-sharp'. You can obtain a copy from both the CVS + repository or the anonymous CVS repository. + + To pull your copy type: + + cvs co gtk-sharp + + Documentation lives in gtk-sharp/doc/en. The "en" indicates the + English language, the first one we are targeting. We can later + do translations, but for now we are focusing on a single + language. + + In that directory you will find the documentation organized by + namespaces. One directory per namespace. In the directories + you will find one XML file per class that needs to be + documented. The mission is to fill in the data with useful + information. Feel free to grab liberally information from the + Gtk documentation from: + + <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a> + + Of course, the API does not apply directly. It only applies at + a foundational level, so you can not really just copy and + paste. Summaries, and remarks sections can probably be lifted + with little or no effort. + + Gtk# uses properties to represent get/set operations in the C + API, so you can also use some bits from there. + + Most of the documentation contains already place holders for + text, we use the internationally approved phrase for this + purpose, `To be added'. So the quest is to remove all of the + "To be added" strings with information with resembles as closely + as possible the toolkit reality. + +*** The pieces to be filled. + + Summaries are one or two line descriptions of the element + (class, struct, interface, method, field, event, delegate), and + its used to render summary pages. So it has to be short. + + The "remarks" section is used to describe in detail the element. + +**** Tags. + + As you document Gtk# you will have a number of tags that you can + use inside the summary and remarks sections, these are: + + <para> </para> + Used to separate paragraphs. + + <paramref name="param_name"/> + Used to reference a formal parameter to a function. + + <see cref="T:SomeTypeName"/> + Use this to reference a type, this will include an hyper + link to the page for type SomeTypeName. + + For example, to reference "System.Enum", do: + + <see cref="T:System.Enum"/> + + <see cref="P:SomeTypeName.Property"/> + Use this to reference a property, this will include an hyper + link to the page for the property `Property' of type `SomeTypeName'. + + For example, to reference the BaseType property in System.Type, do: + + <see cref="P:System.Type.BaseType"/> + + <see cref="M:SomeTypeName.Method(type,type)"/> + Use this to reference a method, this will include an hyper + link to the page for the method `Method' of type `SomeTypeName'. + + For example, to reference the ToString method in System.Object, do: + + <see cref="M:System.Object.ToString()"/> + + <see langword="keywrod"/> + Use this to link to a keyword in the C# language, for + example to link to `true', do: + + <see langword="true"/> + + <example> ... </example> + + Use example to insert an example. The example can + contain explanatory text and code. + + <code lang="C#">.. </code> + + Use this to provide a sample C# program, typically used + within the <example> tags. + + When providing examples, try to provide a full example, + we would like to be able to have a button to compile and + run samples embedded into the documentation, or pop up + an editor to let the user play with the sample. + + You can link to an example like this: + + <code lang="C#" source="file.cs"> </code> + + <item> + + <list type="bullet"> </list> + + Use this to create lists. Lists contains <item> + elements + + <list type="table"> </lits> + <listheader> + <term>YOUR FIRST COLUMN</term> + <description>YOUR DESCRIPTION</description> + </listheader> + + For two-column tables. Inside use: + + <item> + <term>First</term> + <description>First descritpion</description> + </item> + <item> + <term>Second</term> + <description>Second descirption</description> + </item> + +** Words of warning. + A few words of warning and advice for class documentors: A well-documented API can ease hours of frustration; as Mono diff --git a/web/index b/web/index index 2294b1f2850..cabd7564f4b 100644 --- a/web/index +++ b/web/index @@ -102,6 +102,19 @@ </tr> </table> +@item Feb 18th, 2003: Volunteers to document Gtk# + + With the availability of a documentation browser, we are + looking for volunteers to help us complete the documentation + of the Gtk# binding for Mono. + + Experience with Gtk is useful, but not mandatory. We have + checked in stubs, and we have instructions, and resources to + how to complete this process <a + href="documentation.html">here</a>. Mail the <a + href="mailto:mono-docs-list@ximian.com">mono-docs-list@ximian.com</a> + for further discussion. + @item Feb 14th, 2003: OpenGL# bindings for Mono; Mono Basic updates. Mark Crichton has completed his OpenGL/GLUT bindings for |