Re: 'args' in Gtk+

[Owen Taylor <otaylor redhat com>]

Lee <lee0@callnetuk.com> writes:

> Hi,
> 
> In the process of writing docs for the RDP, I've come across "args"
> sections that I'm (presumably) supposed to document.
> 
> Except I'm not quite certain how the whole "args" thing fits into the
> Gtk+ system.
> More importantly, I'm not sure what to say about the 'args' for a widget
> that won't already be said elsewhere in the docs.
> 
> If someone could summarise the role of "args" and/or what would be
> appropriate documentation for each one, I'd appreciate it.

"Arguments" are basically attributes that can be queried
and set by the application.

Usually, they correspond to get and/or set functions;
for instance GtkLabel::justify corresponds
to gtk_label_set_justify. 

As far as documentation goes, there are three approaches
that could be taken:

 1) Document the attribute as an argument, refer to that
    description from the set() function.

 2) Document the attribute with the set() function, refer
    to that from the argument description.

 3) Document the attribute in both places independently.

I'm not sure which is the best approach - it's a
matter of style and should be added to the style
guide, but as a first pass, any of the three
should do.

Regards,
                                        Owen