Re: Style questions for RDP

[Damon Chaplin <damon karuna freeserve co uk>]

Owen Taylor wrote:
> 
> [ 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.

Yes, we definitely need one. I'll write it, and include all the
issues we discuss. And I'll try to find a suitable widget to
document.

 
> 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')

I prefer the 'looks' version, though I'm not sure why. I think if you use
'Look up a key...' it isn't quite as clear that it relates to the function.

Looking at the MSVC++ manual all the descriptions start with something like
'The gets function reads a line...'. I don't think we want
'The XXX function/macro ...' for every description, do we?

In GLib I also tried to make the first sentence of the description a short
summary of what the function did, so that it might be possible to produce a
very short 'quick reference' which could be printed out. I don't know whether
its worth doing this, though.


>     @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.

I think the 'a GHashTable' empahizes the object-oriented nature.
Personally I think the articles make it easier to read - it flows a bit
better.

(Incidentally, do we want everyone to stick with American spellings?
I suppose we should, though I may make mistakes.)


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

The other option is to use tables (or informaltables, since we probably won't
want titles). Tables may look nicer as they break up the monotonous text a
bit, and we can add background colors. And they can be more compact than
variablelists.

Maybe we should define a few 'role's we use to tag elements like these
so we can add specific DSSSL code for them if we want to,
e.g. for enums:

<informaltable pgwide=1 frame="none" role="enum">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><symbol>GTK_ARROW_UP</symbol></entry>
<entry>an arrow pointing up.</entry>
</row>
<row>
<entry><symbol>GTK_ARROW_DOWN</symbol></entry>
<entry>an arrow pointing down.</entry>
</row>
</tbody></tgroup></informaltable>

or for structs:

<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry><structfield>GTK_ARROW_UP</structfield></entry>
<entry>an arrow pointing up.</entry>
</row>
<row>
<entry><structfield>GTK_ARROW_DOWN</structfield></entry>
<entry>an arrow pointing down.</entry>
</row>
</tbody></tgroup></informaltable>

The SGML is a bit complicated, but using variablelist is just as bad.
 
 
>  - 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.

I favour tables again, for the same reasons. I doubt the source code will
include enough documentation. Actually if we add the public fields to the
table ourselves, then we don't need to alter the GTK+ source at all.
(We were thinking of using /*< public >*/ and /*< private >*/ to mark fields
in the widget structs.)

I think maybe the C struct should still be included in the docs, as it makes
it
obvious it is a struct. But we could strip out the comments inside the
struct once our own documentation is complete. I'm not sure. Maybe we should
remove the actual struct completely.

 
>  - 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?

Currently it follows the GTK+ header files, so enums in gtkenums.h are all
in the 'Standard Enumerations' section. Quite a few of them are specific to
a widget and so should probably be moved into the widget's section. I
think the others can be left in 'Standard Enumerations'. The cross-referencing
links makes it easy to find them anyway.

(Using gtk-doc if you move a function/enumeration to another section and run
'make templates', its description is automatically moved to the new section,
which is quite helpful.)

Damon