doc/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
  30                 * A guide to Mono as compared to the Microsoft.NET
  31                   Framework SDK
  32
  33         </ul>
  34
  35 * Class Library documentation
  36
  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>.
  39
  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.
  43
  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.
  48
  49 ** Gtk# documentation
  50
  51         We also have a large body of class libraries that are specific
  52         to Mono, for example the documentation for Gtk#.
  53
  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
  59         site</a>.
  60
  61         To get started:
  62
  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.
  66
  67         To pull your copy type:
  68
  69 <pre>
  70                 cvs co gtk-sharp
  71 </pre>
  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
  75         language.
  76
  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:
  83
  84         <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>
  85
  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.
  90
  91         Gtk# uses properties to represent get/set operations in the C
  92         API, so you can also use some bits from there.
  93
  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.
  99
 100 *** The pieces to be filled.
 101
 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.
 105
 106         The "remarks" section is used to describe in detail the element.
 107
 108 **** Tags.
 109
 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:
 112
 113 <pre>
 114 &lt;para&gt; &lt;/para&gt;
 115 </pre>
 116                 Used to separate paragraphs.
 117
 118 <pre>
 119 &lt;paramref name="param_name"/&gt;
 120 </pre>
 121                 Used to reference a formal parameter to a function.
 122
 123 <pre>
 124 &lt;see cref="T:SomeTypeName"/&gt;
 125 </pre>
 126                 Use this to reference a type, this will include an hyper
 127                 link to the page for type SomeTypeName.
 128
 129                 For example, to reference "System.Enum", do:
 130
 131 <pre>
 132         &lt;see cref="T:System.Enum"/&gt;
 133 </pre>
 134
 135 <pre>
 136 &lt;see cref="P:SomeTypeName.Property"/&gt;
 137 </pre>
 138                 Use this to reference a property, this will include an hyper
 139                 link to the page for the property `Property' of type `SomeTypeName'.
 140
 141                 For example, to reference the BaseType property in System.Type, do:
 142
 143 <pre>
 144         &lt;see cref="P:System.Type.BaseType"/&gt;
 145 </pre>
 146
 147 <pre>
 148 &lt;see cref="M:SomeTypeName.Method(type,type)"/&gt;
 149 </pre>
 150                 Use this to reference a method, this will include an hyper
 151                 link to the page for the method `Method' of type `SomeTypeName'.
 152
 153                 For example, to reference the ToString method in System.Object, do:
 154
 155 <pre>
 156         &lt;see cref="M:System.Object.ToString()"/&gt;
 157 </pre>
 158
 159 <pre>
 160 &lt;see langword="keyword"/&gt;
 161 </pre>
 162                 Use this to link to a keyword in the C# language, for
 163                 example to link to `true', do:
 164
 165 <pre>
 166         &lt;see langword="true"/&gt;
 167 </pre>
 168
 169 <pre>
 170 &lt;example&gt; ... &lt;/example&gt;
 171 </pre>
 172                 Use example to insert an example.  The example can
 173                 contain explanatory text and code.
 174
 175 <pre>
 176 &lt;code lang="C#"&gt;.. &lt;/code&gt;
 177 </pre>
 178
 179                 Use this to provide a sample C# program, typically used
 180                 within the &lt;example&gt; tags.
 181
 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.
 186
 187                 You can link to an example like this:
 188
 189 <pre>
 190         &lt;code lang="C#" source="file.cs"&gt; &lt;/code&gt;
 191 </pre>
 192
 193 <pre>
 194 &lt;item&gt;
 195 </pre>
 196
 197 <pre>
 198 &lt;list type="bullet"&gt;  &lt;/list&gt;
 199 </pre>
 200
 201                 Use this to create lists.  Lists contains &lt;item&gt;
 202                 elements
 203
 204 <pre>
 205 &lt;list type="table"&gt; &lt;/lits&gt;
 206             &lt;listheader&gt;
 207               &lt;term&gt;YOUR FIRST COLUMN&lt;/term&gt;
 208               &lt;description&gt;YOUR DESCRIPTION&lt;/description&gt;
 209             &lt;/listheader&gt;
 210 </pre>
 211                 For two-column tables.  Inside use:
 212
 213 <pre>
 214 &lt;item&gt;
 215         &lt;term&gt;First&lt;/term&gt;
 216         &lt;description&gt;First descritpion&lt;/description&gt;
 217 &lt;/item&gt;
 218 &lt;item&gt;
 219         &lt;term&gt;Second&lt;/term&gt;
 220         &lt;description&gt;Second descirption&lt;/description&gt;
 221 &lt;/item&gt;
 222 </pre>
 223
 224 ** Words of warning.
 225
 226         A few words of warning and advice for class documentors:
 227
 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:
 233
 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
 239         documenting a type.
 240
 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
 247         you document.
 248
 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.