X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=web%2Fdocumentation;h=40085e851267d8d531235348427d9044e53fa07f;hb=1617834754c378d82bc84ba0a752ea10d4d1a117;hp=fe3d61a8d25fdd80816c6a91eb4228272e2c1106;hpb=ed0239040063ef73396b0c9db79a27999b2a7d58;p=mono.git diff --git a/web/documentation b/web/documentation index fe3d61a8d25..40085e85126 100644 --- a/web/documentation +++ b/web/documentation @@ -14,22 +14,247 @@
+ 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. +