Re: Style questions for RDP (Args)

[Damon Chaplin <damon karuna freeserve co uk>]

Federico Mena Quintero wrote:
> 
> >   - 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.
> 
> Does gtk-doc allow for documentation of object arguments?  Other than
> being required for complete documentation of the Gtk widgets, I am
> interested in this because of GnomeCanvas.  All the canvas item
> parameters are dealt with as object arguments, so I need a way to
> document them.

I'll have a go at adding support for Args to the scanning part of gtk-doc
today. I'm not sure how we want the final SGML output to look.

1) Do we want a separate RefSect1 for each Arg (just like each function),
   or do we want a more compact form?

2) Although most Args only 'swallow' one value, some take more - e.g. the
   signal handler Args take a handler function and user data.
    (These Arg types take 2 values: GTK_TYPE_SIGNAL, GTK_TYPE_ARGS,
     GTK_TYPE_FOREIGN, GTK_TYPE_C_CALLBACK. GTK_TYPE_CALLBACK takes 3).

For each Arg we have:

1) The Arg name, e.g. "GtkWindow::type". We probably only want to use "type".
2) The Arg type, e.g. GTK_TYPE_WINDOW_TYPE, GTK_TYPE_STRING etc.
3) The Arg flags, e.g. GTK_ARG_READWRITE, GTK_ARG_CHILD_ARG,
     GTK_ARG_CONSTRUCT_ONLY.


Should the output be something like this (for GtkWindow):

Args

"type" (GtkWindowType : Read-Write)

  The type of the window.

"title" (gchar* : Read-Write)

  The window title.

"auto_shrink" (gboolean : Read-Write)

  If the window shrinks automatically when widgets inside it shrink.

"position" (GtkWindowPosition : Read-Write)

  The position of the window.


I need to be able to turn types like GTK_TYPE_WINDOW_TYPE into a link to the
GtkWindowType enum. I think that's possible.


For Args with 2 values we could simply show all the value types, e.g.

"signal" (GtkSignalFunc, gpointer : Writable)

  Sets a signal handler.



So in the template files, I will just leave space for the description. We
won't
worry about having separate descriptions for each value for 2 & 3-value Args
since they are rarely used. e.g.

<!-- ##### ARG GtkWindow::type ##### -->
<para>
The type of the window.
</para>


OK?

Damon