* 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:
cvs co gtk-sharpDocumentation 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: http://developer.gnome.org/doc/API/ 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:
Used to separate paragraphs.
Used to reference a formal parameter to a function.
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:
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:
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:
Use this to link to a keyword in the C# language, for example to link to `true', do:
Use example to insert an example. The example can contain explanatory text and code....
..
Use this to provide a sample C# program, typically used
within the
Use this to create lists. Lists contains
For two-column tables. Inside use:
YOUR FIRST COLUMN YOUR DESCRIPTION
** 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 (jbarn@httcb.net) 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. 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.First First descritpion Second Second descirption