Style questions for RDP

[Owen Taylor <otaylor redhat com>]

[ Message Cc'd because I'm not sure everybody is subscribed to
  gtk-doc-list yet ]

I've been beginning some serious work on the RDP, and
one thing that I'm noticing is that we need a 
style guide - both so we have consistency, and so
people doing documentation don't have to think about
such issues.

Probably, this needs to just needs to be one widget
done well and heavily commented, which happens to have 
everything that we need.

I can do this myself (eventually) but perhaps someone
else wants to take up this task.

Some issues that need to be covered:

 - The description of functions and function parameters

   The style used in GLib documentation is:

====
<!-- ##### FUNCTION g_hash_table_lookup ##### -->
<para>
Looks up a key in the #GHashTable, returning the associated value or NULL
if the key is not found.
</para>

@hash_table: a #GHashTable.
@key: the key to look up.
@Returns: the associated value, or NULL if the key is not found.
====

    Note:
   
    The function description uses 'looks' not 'look'.
    (Implying that the omitted portion is 'this function' 
    not 'you use this function to')

    @hash_table (the "object") uses 'a', while the
    remaining parameters use 'the'. I'm happy with this style
    though I might, myself, be more telegraphic and omit
    the articles.

 - How enumeration members are described (I've been
   using a <variablelist>

 - How to describe a structure. (gtk-doc sticks the
   structure from the C file into the output). 
   Do we use a <variablelist> for that as well?

 - How to describe the data members of a widget structure.

 - Are enumerations that are specific to a particular
   widget (but present in gtkenums.h) documenated with
   that widget? Where do enumerations used multiple places
   get documented?

Regards,
                                        Owen