Style questions for RDP
- From: Owen Taylor <otaylor redhat com>
- To: gtk-doc-list redhat com, dcm redhat com, damon karuna freeserve co uk
- Subject: Style questions for RDP
- Date: 07 Mar 1999 14:20:57 -0500
[ 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
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 ##### -->
Looks up a key in the #GHashTable, returning the associated value or NULL
if the key is not found.
@hash_table: a #GHashTable.
@key: the key to look up.
@Returns: the associated value, or NULL if the key is not found.
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
- 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
[Date Prev][Date Next
] [Thread Prev][Thread Next