web/documentation

   1 * Documentation
   2
   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
   6         for Mono.
   7
   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.
  11
  12         We need documentation on a number of topics:
  13
  14         <ul>
  15
  16                 * The development tools (compilers, assembler tools,
  17                   language reference, design time features): these
  18                   live in the `monodoc' CVS module.
  19
  20                 * Frequently Asked Question compilations.
  21
  22                 * HOWTO documents.
  23
  24                 * The Class Libraries (Both the original .NET class
  25                   libraries as well as the class libraries produced by
  26                   the project).
  27
  28                 * Tutorials on Mono and the specifics of running it
  29                   (The <a href="http://www.monohispano.org">Mono
  30                   Hispano</a> team has produced lots of <a
  31                   href="http://www.monohispano.org/tutoriales.php">tutorials
  32                   in spanish</a>
  33
  34                 * A guide to Mono as compared to the Microsoft.NET
  35                   Framework SDK
  36
  37         </ul>
  38
  39 * Class Library documentation
  40
  41         We are moving to a new setup for documenting the class libraries,
  42         and you can read about it <a href="classlib-doc.html">here</a>.
  43
  44         There are two classes of documentation: free documentation for
  45         existing .NET classes and documentation for the classes that
  46         we have developed on top of .NET.
  47
  48         There is a large body of documentation that came from the ECMA
  49         standarization effort that has been checked into CVS.  It does
  50         not contain everything Mono and .NET have, so they need to be
  51         updated and augmented.
  52
  53 ** Gtk# documentation
  54
  55         We also have a large body of class libraries that are specific
  56         to Mono, for example the documentation for Gtk#.
  57
  58         We have checked in stub documentation for Gtk# into the CVS
  59         repository (on gtk-sharp/doc) and we need volunteers to help
  60         populate the documentation for it.  Since Gtk# is a wrapper
  61         for Gtk, plenty of documentation exists in the <a
  62         href="http://developer.gnome.org/doc/API">Gnome developer
  63         site</a>.
  64
  65         To get started:
  66
  67         You need to download Gtk# from the CVS repository.  The module
  68         name is `gtk-sharp'.  You can obtain a copy from both the CVS
  69         repository or the anonymous CVS repository.
  70
  71         To pull your copy type:
  72
  73 <pre>
  74                 cvs co gtk-sharp
  75 </pre>
  76         Documentation lives in gtk-sharp/doc/en.  The "en" indicates the
  77         English language, the first one we are targeting.  We can later
  78         do translations, but for now we are focusing on a single
  79         language.
  80
  81         In that directory you will find the documentation organized by
  82         namespaces.  One directory per namespace.  In the directories
  83         you will find one XML file per class that needs to be
  84         documented.  The mission is to fill in the data with useful
  85         information.  Feel free to grab liberally information from the
  86         Gtk documentation from:
  87
  88         <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>
  89
  90         Of course, the API does not apply directly.  It only applies at
  91         a foundational level, so you can not really just copy and
  92         paste.  Summaries, and remarks sections can probably be lifted
  93         with little or no effort.
  94
  95         Gtk# uses properties to represent get/set operations in the C
  96         API, so you can also use some bits from there.
  97
  98         Most of the documentation contains already place holders for
  99         text, we use the internationally approved phrase for this
 100         purpose, `To be added'.  So the quest is to remove all of the
 101         "To be added" strings with information with resembles as closely
 102         as possible the toolkit reality.
 103
 104 *** The pieces to be filled.
 105
 106         Summaries are one or two line descriptions of the element
 107         (class, struct, interface, method, field, event, delegate), and
 108         its used to render summary pages.  So it has to be short.
 109
 110         The "remarks" section is used to describe in detail the element.
 111
 112 **** Tags.
 113
 114         As you document Gtk# you will have a number of tags that you can
 115         use inside the summary and remarks sections, these are:
 116
 117 <pre>
 118 &lt;para&gt; &lt;/para&gt;
 119 </pre>
 120                 Used to separate paragraphs.
 121
 122 <pre>
 123 &lt;paramref name="param_name"/&gt;
 124 </pre>
 125                 Used to reference a formal parameter to a function.
 126
 127 <pre>
 128 &lt;see cref="T:SomeTypeName"/&gt;
 129 </pre>
 130                 Use this to reference a type, this will include an hyper
 131                 link to the page for type SomeTypeName.
 132
 133                 For example, to reference "System.Enum", do:
 134
 135 <pre>
 136         &lt;see cref="T:System.Enum"/&gt;
 137 </pre>
 138
 139 <pre>
 140 &lt;see cref="P:SomeTypeName.Property"/&gt;
 141 </pre>
 142                 Use this to reference a property, this will include an hyper
 143                 link to the page for the property `Property' of type `SomeTypeName'.
 144
 145                 For example, to reference the BaseType property in System.Type, do:
 146
 147 <pre>
 148         &lt;see cref="P:System.Type.BaseType"/&gt;
 149 </pre>
 150
 151 <pre>
 152 &lt;see cref="M:SomeTypeName.Method(type,type)"/&gt;
 153 </pre>
 154                 Use this to reference a method, this will include an hyper
 155                 link to the page for the method `Method' of type `SomeTypeName'.
 156
 157                 For example, to reference the ToString method in System.Object, do:
 158
 159 <pre>
 160         &lt;see cref="M:System.Object.ToString()"/&gt;
 161 </pre>
 162
 163 <pre>
 164 &lt;see langword="keyword"/&gt;
 165 </pre>
 166                 Use this to link to a keyword in the C# language, for
 167                 example to link to `true', do:
 168
 169 <pre>
 170         &lt;see langword="true"/&gt;
 171 </pre>
 172
 173 <pre>
 174 &lt;example&gt; ... &lt;/example&gt;
 175 </pre>
 176                 Use example to insert an example.  The example can
 177                 contain explanatory text and code.
 178
 179 <pre>
 180 &lt;code lang="C#"&gt;.. &lt;/code&gt;
 181 </pre>
 182
 183                 Use this to provide a sample C# program, typically used
 184                 within the &lt;example&gt; tags.
 185
 186                 When providing examples, try to provide a full example,
 187                 we would like to be able to have a button to compile and
 188                 run samples embedded into the documentation, or pop up
 189                 an editor to let the user play with the sample.
 190
 191                 You can link to an example like this:
 192
 193 <pre>
 194         &lt;code lang="C#" source="file.cs"&gt; &lt;/code&gt;
 195 </pre>
 196
 197 <pre>
 198 &lt;item&gt;
 199 </pre>
 200
 201 <pre>
 202 &lt;list type="bullet"&gt;  &lt;/list&gt;
 203 </pre>
 204
 205                 Use this to create lists.  Lists contains &lt;item&gt;
 206                 elements which have to contain &lt;term&gt; containers.
 207
 208 <pre>
 209 &lt;list type="table"&gt; &lt;/lits&gt;
 210             &lt;listheader&gt;
 211               &lt;term&gt;YOUR FIRST COLUMN&lt;/term&gt;
 212               &lt;description&gt;YOUR DESCRIPTION&lt;/description&gt;
 213             &lt;/listheader&gt;
 214 </pre>
 215                 For two-column tables.  Inside use:
 216
 217 <pre>
 218 &lt;item&gt;
 219         &lt;term&gt;First&lt;/term&gt;
 220         &lt;description&gt;First descritpion&lt;/description&gt;
 221 &lt;/item&gt;
 222 &lt;item&gt;
 223         &lt;term&gt;Second&lt;/term&gt;
 224         &lt;description&gt;Second descirption&lt;/description&gt;
 225 &lt;/item&gt;
 226 </pre>
 227
 228 ** Words of warning.
 229
 230         A few words of warning and advice for class documentors:
 231
 232         A well-documented API can ease hours of frustration; as Mono
 233         matures, robust and complete class library documentation will
 234         become increasingly important.  As you write API documentation,
 235         whether it is embedded in source files or in external Monodoc XML,
 236         please keep the following in mind:
 237
 238         Plagarism, even if it's unintentional, is a Bad Thing(TM).
 239         Microsoft's .NET Framework Class Library documentation is an
 240         excellent resource for understanding the behavior and properties of
 241         a type, and a lot of hard work went in to creating this (copyrighted)
 242         resource.  Please don't copy from Microsoft's reference when
 243         documenting a type.
 244
 245         To avoid this, I (<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>)
 246         suggest that you read the complete Microsoft documentation for a type,
 247         ponder it for a while, and write the Mono documentation in your own
 248         words.  While it's certainly okay to refer to the Microsoft
 249         documentation to clarify your understanding of behavior or properties,
 250         please don't open the Microsoft docs and refer to them for each member
 251         you document.
 252
 253         The best way of documenting is to read our source code
 254         implementation and explain in your own words what our implementation
 255         does, and what the user can do with it.
 256
 257         There's a lot of domain expertise among the class library contributors;
 258         let's put the same personal stamp on the class library documentation
 259         that we have on the class libraries themselves.
 260