<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.
+ * 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>
-** Class Library documentation
+* Class Library documentation
- When contributing to the Class Library effort, please use the
- inline XML documentation tags to document your classes so we
- can automatically generate the documentation from the class
- libraries.
+ 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>.
- If you provide examples, please do not embed them into the
- source code, as that will make the source code harder to read
- and maintain. Instead, put examples for your code into a
- subdirectory of the class libraries. Make your sample
- code a full standalone application that people can compile.
- Ideally the Mono documentation browser will let you edit, modify
- and run the sample programs.
+ 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>
+<para> </para>
+</pre>
+ Used to separate paragraphs.
+
+<pre>
+<paramref name="param_name"/>
+</pre>
+ Used to reference a formal parameter to a function.
+
+<pre>
+<see cref="T:SomeTypeName"/>
+</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>
+ <see cref="T:System.Enum"/>
+</pre>
+
+<pre>
+<see cref="P:SomeTypeName.Property"/>
+</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>
+ <see cref="P:System.Type.BaseType"/>
+</pre>
+
+<pre>
+<see cref="M:SomeTypeName.Method(type,type)"/>
+</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>
+ <see cref="M:System.Object.ToString()"/>
+</pre>
+
+<pre>
+<see langword="keyword"/>
+</pre>
+ Use this to link to a keyword in the C# language, for
+ example to link to `true', do:
+
+<pre>
+ <see langword="true"/>
+</pre>
+
+<pre>
+<example> ... </example>
+</pre>
+ Use example to insert an example. The example can
+ contain explanatory text and code.
+
+<pre>
+<code lang="C#">.. </code>
+</pre>
+
+ 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:
+
+<pre>
+ <code lang="C#" source="file.cs"> </code>
+</pre>
+
+<pre>
+<item>
+</pre>
+
+<pre>
+<list type="bullet"> </list>
+</pre>
+
+ Use this to create lists. Lists contains <item>
+ elements which have to contain <term> containers.
+
+<pre>
+<list type="table"> </lits>
+ <listheader>
+ <term>YOUR FIRST COLUMN</term>
+ <description>YOUR DESCRIPTION</description>
+ </listheader>
+</pre>
+ For two-column tables. Inside use:
+
+<pre>
+<item>
+ <term>First</term>
+ <description>First descritpion</description>
+</item>
+<item>
+ <term>Second</term>
+ <description>Second descirption</description>
+</item>
+</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
+ matures, robust and complete class library documentation will
+ become increasingly important. As you write API documentation,
+ whether it is embedded in source files or in external Monodoc XML,
+ please keep the following in mind:
+
+ Plagarism, even if it's unintentional, is a Bad Thing(TM).
+ Microsoft's .NET Framework Class Library documentation is an
+ excellent resource for understanding the behavior and properties of
+ a type, and a lot of hard work went in to creating this (copyrighted)
+ resource. Please don't copy from Microsoft's reference when
+ documenting a type.
+
+ To avoid this, I (<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>)
+ suggest that you read the complete Microsoft documentation for a type,
+ ponder it for a while, and write the Mono documentation in your own
+ words. While it's certainly okay to refer to the Microsoft
+ documentation to clarify your understanding of behavior or properties,
+ 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
+ that we have on the class libraries themselves.
projects / mono.git / blobdiff