diff options
Diffstat (limited to 'web/documentation')
-rw-r--r-- | web/documentation | 260 |
1 files changed, 0 insertions, 260 deletions
diff --git a/web/documentation b/web/documentation deleted file mode 100644 index 40085e85126..00000000000 --- a/web/documentation +++ /dev/null @@ -1,260 +0,0 @@ -* Documentation - - Although most of the concepts from Microsoft.NET can - be applied to the completed Mono platform, we do need to - have a complete set of free documentation written specifically - for Mono. - - The documentation license we have chosen is the GNU Free - Documentation License (FDL), the standard for most documents - in the free software world. - - We need documentation on a number of topics: - - <ul> - - * The development tools (compilers, assembler tools, - language reference, design time features): these - live in the `monodoc' CVS module. - - * Frequently Asked Question compilations. - - * HOWTO documents. - - * 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 - (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 - - 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> -<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. - |