3 Although most of the concepts from Microsoft.NET can
4 be applied to the completed Mono platform, we do need to
5 have a complete set of free documentation written specifically
8 The documentation license we have chosen is the GNU Free
9 Documentation License (FDL), the standard for most documents
10 in the free software world.
12 We need documentation on a number of topics:
16 * The development tools (compilers, assembler tools,
17 language reference, design time features): these
18 live in the `monodoc' CVS module.
20 * Frequently Asked Question compilations.
24 * The Class Libraries (Both the original .NET class
25 libraries as well as the class libraries produced by
28 * Tutorials on Mono and the specifics of running it.
30 * A guide to Mono as compared to the Microsoft.NET
35 * Class Library documentation
37 We are moving to a new setup for documenting the class libraries,
38 and you can read about it <a href="classlib-doc.html">here</a>.
40 There are two classes of documentation: free documentation for
41 existing .NET classes and documentation for the classes that
42 we have developed on top of .NET.
44 There is a large body of documentation that came from the ECMA
45 standarization effort that has been checked into CVS. It does
46 not contain everything Mono and .NET have, so they need to be
47 updated and augmented.
51 We also have a large body of class libraries that are specific
52 to Mono, for example the documentation for Gtk#.
54 We have checked in stub documentation for Gtk# into the CVS
55 repository (on gtk-sharp/doc) and we need volunteers to help
56 populate the documentation for it. Since Gtk# is a wrapper
57 for Gtk, plenty of documentation exists in the <a
58 href="http://developer.gnome.org/doc/API">Gnome developer
63 You need to download Gtk# from the CVS repository. The module
64 name is `gtk-sharp'. You can obtain a copy from both the CVS
65 repository or the anonymous CVS repository.
67 To pull your copy type:
72 Documentation lives in gtk-sharp/doc/en. The "en" indicates the
73 English language, the first one we are targeting. We can later
74 do translations, but for now we are focusing on a single
77 In that directory you will find the documentation organized by
78 namespaces. One directory per namespace. In the directories
79 you will find one XML file per class that needs to be
80 documented. The mission is to fill in the data with useful
81 information. Feel free to grab liberally information from the
82 Gtk documentation from:
84 <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>
86 Of course, the API does not apply directly. It only applies at
87 a foundational level, so you can not really just copy and
88 paste. Summaries, and remarks sections can probably be lifted
89 with little or no effort.
91 Gtk# uses properties to represent get/set operations in the C
92 API, so you can also use some bits from there.
94 Most of the documentation contains already place holders for
95 text, we use the internationally approved phrase for this
96 purpose, `To be added'. So the quest is to remove all of the
97 "To be added" strings with information with resembles as closely
98 as possible the toolkit reality.
100 *** The pieces to be filled.
102 Summaries are one or two line descriptions of the element
103 (class, struct, interface, method, field, event, delegate), and
104 its used to render summary pages. So it has to be short.
106 The "remarks" section is used to describe in detail the element.
110 As you document Gtk# you will have a number of tags that you can
111 use inside the summary and remarks sections, these are:
114 <para> </para>
116 Used to separate paragraphs.
119 <paramref name="param_name"/>
121 Used to reference a formal parameter to a function.
124 <see cref="T:SomeTypeName"/>
126 Use this to reference a type, this will include an hyper
127 link to the page for type SomeTypeName.
129 For example, to reference "System.Enum", do:
132 <see cref="T:System.Enum"/>
136 <see cref="P:SomeTypeName.Property"/>
138 Use this to reference a property, this will include an hyper
139 link to the page for the property `Property' of type `SomeTypeName'.
141 For example, to reference the BaseType property in System.Type, do:
144 <see cref="P:System.Type.BaseType"/>
148 <see cref="M:SomeTypeName.Method(type,type)"/>
150 Use this to reference a method, this will include an hyper
151 link to the page for the method `Method' of type `SomeTypeName'.
153 For example, to reference the ToString method in System.Object, do:
156 <see cref="M:System.Object.ToString()"/>
160 <see langword="keyword"/>
162 Use this to link to a keyword in the C# language, for
163 example to link to `true', do:
166 <see langword="true"/>
170 <example> ... </example>
172 Use example to insert an example. The example can
173 contain explanatory text and code.
176 <code lang="C#">.. </code>
179 Use this to provide a sample C# program, typically used
180 within the <example> tags.
182 When providing examples, try to provide a full example,
183 we would like to be able to have a button to compile and
184 run samples embedded into the documentation, or pop up
185 an editor to let the user play with the sample.
187 You can link to an example like this:
190 <code lang="C#" source="file.cs"> </code>
198 <list type="bullet"> </list>
201 Use this to create lists. Lists contains <item>
205 <list type="table"> </lits>
207 <term>YOUR FIRST COLUMN</term>
208 <description>YOUR DESCRIPTION</description>
211 For two-column tables. Inside use:
215 <term>First</term>
216 <description>First descritpion</description>
219 <term>Second</term>
220 <description>Second descirption</description>
226 A few words of warning and advice for class documentors:
228 A well-documented API can ease hours of frustration; as Mono
229 matures, robust and complete class library documentation will
230 become increasingly important. As you write API documentation,
231 whether it is embedded in source files or in external Monodoc XML,
232 please keep the following in mind:
234 Plagarism, even if it's unintentional, is a Bad Thing(TM).
235 Microsoft's .NET Framework Class Library documentation is an
236 excellent resource for understanding the behavior and properties of
237 a type, and a lot of hard work went in to creating this (copyrighted)
238 resource. Please don't copy from Microsoft's reference when
241 To avoid this, I (<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>)
242 suggest that you read the complete Microsoft documentation for a type,
243 ponder it for a while, and write the Mono documentation in your own
244 words. While it's certainly okay to refer to the Microsoft
245 documentation to clarify your understanding of behavior or properties,
246 please don't open the Microsoft docs and refer to them for each member
249 There's a lot of domain expertise among the class library contributors;
250 let's put the same personal stamp on the class library documentation
251 that we have on the class libraries themselves.