From f8c9c8751290f47fa17fa5851ce97ddc9c443bf4 Mon Sep 17 00:00:00 2001 From: Gonzalo Paniagua Javier Date: Fri, 22 Oct 2010 12:52:19 -0400 Subject: Sniff, sniff Remove the old (really) stuff to generate the website from makefiles. --- web/documentation | 260 ------------------------------------------------------ 1 file changed, 260 deletions(-) delete mode 100644 web/documentation (limited to 'web/documentation') 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: - - - -* Class Library documentation - - We are moving to a new setup for documenting the class libraries, - and you can read about it here. - - 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 Gnome developer - site. - - 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: - - http://developer.gnome.org/doc/API/ - - 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="keyword"/>
-
- 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 which have to contain <term> containers. - -
-<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 - 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 (jbarn@httcb.net) - 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. - -- cgit v1.2.3