/
documentation
260 lines (196 loc) · 8.58 KB
/
documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
* 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.