[Gtk-sharp-list] Documentation effort: Documenting Gtk#

[Miguel de Icaza]

Hello!

    We have checked into CVS the generated stubs for the Gtk#
documentation.  These stubs are useful on their own for people who want
to quickly browse the API, but it lacks descriptions and lacks
examples.  We need volunteers that want to help document Gtk to step up
and help us here.

* Getting 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:
        
        	cvs co gtk-sharp
        
        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:
        
        	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:
        
        <para> </para>
        	Used to separate paragraphs.
        
        <paramref name="param_name"/>
        	Used to reference a formal parameter to a function.
        
        <see cref="T:SomeTypeName"/>
        	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:
        
        	<see cref="T:System.Enum"/>
        
        <see langword="keywrod"/>
        	Use this to link to a keyword in the C# language, for
        	example to link to `true', do:
        
        		<see langword="true"/>
        
        <example> ... </example>
        
        	Use example to insert an example.  The example can 
        	contain explanatory text and code.
        
        <code lang="C#">.. </code>
        
        	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:
        
        	<code lang="C#" source="file.cs"> </code>
        
        <item>
        	
        <list type="bullet">  </list>
        
        	Use this to create lists.  Lists contains <item>
        	elements
        
        <list type="table"> </lits>
                    <listheader>
                      <term>YOUR FIRST COLUMN</term>
                      <description>YOUR DESCRIPTION</description>
                    </listheader>
        
        	For two-column tables.  Inside use:
        
        	<item>
        		<term>First</term>
        		<description>First descritpion</description>
        	</item>
        	<item>
        		<term>Second</term>
        		<description>Second descirption</description>
        	</item>
        
* Registering your interest

	Subscribe to the mono-docs-list mailing list to coordinate the
	effort.  Since right we do not have a lot of people contributing
	and we do not have a nice web system to track this, only claim
	your documentation block on the list.

	When submitting changes, please send those to mono-docs-list for
	now (we will have a better system later, and we will grant cvs
	accounts for those helping, or those who want to help become the
	documentation maintainers).

	Each document begins with a tag <Type ...>.  Add to that the
	following attribute:

	<Type mono-doc-maintainer="your-name" ...>

	Post your documentation to mono-docs-list@ximian.com

Best wishes,
Miguel.