update known-issues

[mono.git] / web / documentation

diff --git a/web/documentation b/web/documentation
index 4ed2e6a6639195f250598ce651e8d27fecf7e316..40085e851267d8d531235348427d9044e53fa07f 100644 (file)
--- a/web/documentation
+++ b/web/documentation
@@ -14,26 +14,219 @@
        <ul>
 
                * The development tools (compilers, assembler tools,
        <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.
 
 
                * 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. 
+               * Tutorials on Mono and the specifics of running it
+                 (The <a href="http://www.monohispano.org">Mono
+                 Hispano</a> team has produced lots of <a
+                 href="http://www.monohispano.org/tutoriales.php">tutorials
+                 in spanish</a>

 
                * A guide to Mono as compared to the Microsoft.NET
                  Framework SDK
 
        </ul>
 
 
                * A guide to Mono as compared to the Microsoft.NET
                  Framework SDK
 
        </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>.
 
 
        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">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:
+
+<pre>
+               cvs co gtk-sharp
+</pre>
+        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:
+
+<pre>        
+&lt;para&gt; &lt;/para&gt;
+</pre>
+               Used to separate paragraphs.
+      
+<pre>  
+&lt;paramref name="param_name"/&gt;
+</pre>
+               Used to reference a formal parameter to a function.
+
+<pre>  
+&lt;see cref="T:SomeTypeName"/&gt;
+</pre>
+               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:
+        
+<pre>
+       &lt;see cref="T:System.Enum"/&gt;
+</pre>
+
+<pre>
+&lt;see cref="P:SomeTypeName.Property"/&gt;
+</pre>
+               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:
+        
+<pre>
+       &lt;see cref="P:System.Type.BaseType"/&gt;
+</pre>
+
+<pre>
+&lt;see cref="M:SomeTypeName.Method(type,type)"/&gt;
+</pre>
+               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:
+        
+<pre>
+       &lt;see cref="M:System.Object.ToString()"/&gt;
+</pre>
+        
+<pre>
+&lt;see langword="keyword"/&gt;
+</pre>
+               Use this to link to a keyword in the C# language, for
+               example to link to `true', do:
+
+<pre>
+       &lt;see langword="true"/&gt;
+</pre>
+        
+<pre>
+&lt;example&gt; ... &lt;/example&gt;
+</pre>        
+               Use example to insert an example.  The example can 
+               contain explanatory text and code.
+        
+<pre>
+&lt;code lang="C#"&gt;.. &lt;/code&gt;
+</pre>
+        
+               Use this to provide a sample C# program, typically used
+               within the &lt;example&gt; 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:
+
+<pre>
+       &lt;code lang="C#" source="file.cs"&gt; &lt;/code&gt;
+</pre>
+
+<pre>
+&lt;item&gt;
+</pre>
+               
+<pre>
+&lt;list type="bullet"&gt;  &lt;/list&gt;
+</pre>
+        
+               Use this to create lists.  Lists contains &lt;item&gt;
+               elements which have to contain &lt;term&gt; containers.
+        
+<pre>
+&lt;list type="table"&gt; &lt;/lits&gt;
+            &lt;listheader&gt;
+              &lt;term&gt;YOUR FIRST COLUMN&lt;/term&gt;
+              &lt;description&gt;YOUR DESCRIPTION&lt;/description&gt;
+            &lt;/listheader&gt;
+</pre>
+               For two-column tables.  Inside use:
+        
+<pre>
+&lt;item&gt;
+       &lt;term&gt;First&lt;/term&gt;
+       &lt;description&gt;First descritpion&lt;/description&gt;
+&lt;/item&gt;
+&lt;item&gt;
+       &lt;term&gt;Second&lt;/term&gt;
+       &lt;description&gt;Second descirption&lt;/description&gt;
+&lt;/item&gt;
+</pre>
+
+** Words of warning.
+

         A few words of warning and advice for class documentors:
 
         A well-documented API can ease hours of frustration; as Mono
         A few words of warning and advice for class documentors:
 
         A well-documented API can ease hours of frustration; as Mono


@@ -57,6 +250,11 @@
         please don't open the Microsoft docs and refer to them for each member
         you document.
 
         please don't open the Microsoft docs and refer to them for each member
         you document.
 

+       The best way of documenting is to read our source code
+       implementation and explain in your own words what our implementation
+       does, and what the user can do with it.
+

         There's a lot of domain expertise among the class library contributors;
         let's put the same personal stamp on the class library documentation
         There's a lot of domain expertise among the class library contributors;
         let's put the same personal stamp on the class library documentation

-        that we have on the class libraries themselves.
\ No newline at end of file
+        that we have on the class libraries themselves.
+