From d735ab1a601dc0a6a702d2eaffad67366a2230d0 Mon Sep 17 00:00:00 2001 From: Miguel de Icaza Date: Tue, 18 Feb 2003 06:46:42 +0000 Subject: Flush svn path=/trunk/mono/; revision=11673 --- web/documentation | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 159 insertions(+), 3 deletions(-) (limited to 'web/documentation') diff --git a/web/documentation b/web/documentation index 4ed2e6a6639..c78f9eaf080 100644 --- a/web/documentation +++ b/web/documentation @@ -14,13 +14,16 @@ -** Class Library documentation +* 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: + + + Used to separate paragraphs. + + + Used to reference a formal parameter to a function. + + + 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: + + + + + 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: + + + + + 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: + + + + + Use this to link to a keyword in the C# language, for + example to link to `true', do: + + + + ... + + Use example to insert an example. The example can + contain explanatory text and code. + + .. + + Use this to provide a sample C# program, typically used + within the 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: + + + + + + + + Use this to create lists. Lists contains + elements + + + + YOUR FIRST COLUMN + YOUR DESCRIPTION + + + For two-column tables. Inside use: + + + First + First descritpion + + + Second + Second descirption + + +** Words of warning. + A few words of warning and advice for class documentors: A well-documented API can ease hours of frustration; as Mono -- cgit v1.2.3