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/2.0/">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                 cvs co gtk-sharp
  70
  71         Documentation lives in gtk-sharp/doc/en.  The "en" indicates the
  72         English language, the first one we are targeting.  We can later
  73         do translations, but for now we are focusing on a single
  74         language.
  75
  76         In that directory you will find the documentation organized by
  77         namespaces.  One directory per namespace.  In the directories
  78         you will find one XML file per class that needs to be
  79         documented.  The mission is to fill in the data with useful
  80         information.  Feel free to grab liberally information from the
  81         Gtk documentation from:
  82
  83         <a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>
  84
  85         Of course, the API does not apply directly.  It only applies at
  86         a foundational level, so you can not really just copy and
  87         paste.  Summaries, and remarks sections can probably be lifted
  88         with little or no effort.
  89
  90         Gtk# uses properties to represent get/set operations in the C
  91         API, so you can also use some bits from there.
  92
  93         Most of the documentation contains already place holders for
  94         text, we use the internationally approved phrase for this
  95         purpose, `To be added'.  So the quest is to remove all of the
  96         "To be added" strings with information with resembles as closely
  97         as possible the toolkit reality.
  98
  99 *** The pieces to be filled.
 100
 101         Summaries are one or two line descriptions of the element
 102         (class, struct, interface, method, field, event, delegate), and
 103         its used to render summary pages.  So it has to be short.
 104
 105         The "remarks" section is used to describe in detail the element.
 106
 107 **** Tags.
 108
 109         As you document Gtk# you will have a number of tags that you can
 110         use inside the summary and remarks sections, these are:
 111
 112         <para> </para>
 113                 Used to separate paragraphs.
 114
 115         <paramref name="param_name"/>
 116                 Used to reference a formal parameter to a function.
 117
 118         <see cref="T:SomeTypeName"/>
 119                 Use this to reference a type, this will include an hyper
 120                 link to the page for type SomeTypeName.
 121
 122                 For example, to reference "System.Enum", do:
 123
 124                 <see cref="T:System.Enum"/>
 125
 126         <see cref="P:SomeTypeName.Property"/>
 127                 Use this to reference a property, this will include an hyper
 128                 link to the page for the property `Property' of type `SomeTypeName'.
 129
 130                 For example, to reference the BaseType property in System.Type, do:
 131
 132                 <see cref="P:System.Type.BaseType"/>
 133
 134         <see cref="M:SomeTypeName.Method(type,type)"/>
 135                 Use this to reference a method, this will include an hyper
 136                 link to the page for the method `Method' of type `SomeTypeName'.
 137
 138                 For example, to reference the ToString method in System.Object, do:
 139
 140                 <see cref="M:System.Object.ToString()"/>
 141
 142         <see langword="keywrod"/>
 143                 Use this to link to a keyword in the C# language, for
 144                 example to link to `true', do:
 145
 146                         <see langword="true"/>
 147
 148         <example> ... </example>
 149
 150                 Use example to insert an example.  The example can
 151                 contain explanatory text and code.
 152
 153         <code lang="C#">.. </code>
 154
 155                 Use this to provide a sample C# program, typically used
 156                 within the <example> tags.
 157
 158                 When providing examples, try to provide a full example,
 159                 we would like to be able to have a button to compile and
 160                 run samples embedded into the documentation, or pop up
 161                 an editor to let the user play with the sample.
 162
 163                 You can link to an example like this:
 164
 165                 <code lang="C#" source="file.cs"> </code>
 166
 167         <item>
 168
 169         <list type="bullet">  </list>
 170
 171                 Use this to create lists.  Lists contains <item>
 172                 elements
 173
 174         <list type="table"> </lits>
 175                     <listheader>
 176                       <term>YOUR FIRST COLUMN</term>
 177                       <description>YOUR DESCRIPTION</description>
 178                     </listheader>
 179
 180                 For two-column tables.  Inside use:
 181
 182                 <item>
 183                         <term>First</term>
 184                         <description>First descritpion</description>
 185                 </item>
 186                 <item>
 187                         <term>Second</term>
 188                         <description>Second descirption</description>
 189                 </item>
 190
 191 ** Words of warning.
 192
 193         A few words of warning and advice for class documentors:
 194
 195         A well-documented API can ease hours of frustration; as Mono
 196         matures, robust and complete class library documentation will
 197         become increasingly important.  As you write API documentation,
 198         whether it is embedded in source files or in external Monodoc XML,
 199         please keep the following in mind:
 200
 201         Plagarism, even if it's unintentional, is a Bad Thing(TM).
 202         Microsoft's .NET Framework Class Library documentation is an
 203         excellent resource for understanding the behavior and properties of
 204         a type, and a lot of hard work went in to creating this (copyrighted)
 205         resource.  Please don't copy from Microsoft's reference when
 206         documenting a type.
 207
 208         To avoid this, I (<a href="mailto:jbarn@httcb.net">jbarn@httcb.net</a>)
 209         suggest that you read the complete Microsoft documentation for a type,
 210         ponder it for a while, and write the Mono documentation in your own
 211         words.  While it's certainly okay to refer to the Microsoft
 212         documentation to clarify your understanding of behavior or properties,
 213         please don't open the Microsoft docs and refer to them for each member
 214         you document.
 215
 216         There's a lot of domain expertise among the class library contributors;
 217         let's put the same personal stamp on the class library documentation
 218         that we have on the class libraries themselves.