Re: GObject docs improvements

[David Nečas (Yeti) <yeti physics muni cz>]

On Wed, Feb 14, 2007 at 02:52:02PM -0600, Daniel Espinosa wrote:
> 1)  The text "when they register a closure to be invoked upon the
> signal emission" is not clear what is it a "closure"...

Not even when reading the tutorial in order and therefore
getting to this just after reading a whole section on
closures?

> 2) if a signature for a callback is:
>
> return_type function_callback (gpointer instance, ... , gpointer user_data);
>
> How do I know If is it correct to have callback declaration: void
> function_callback (GObjectMyObject *object, gboolen val, MyType type),

Iff `...' is a signle gboolean argument and MyType is
a pointer.  In other words, you can call a function only
with arguments that match the function signature.

Though I agree the text should be more specific about what
`...' stands for here.

> and how to create a new signal that sends the data needed by my
> callback

user data is always a single pointer (of course, you can
write closures and marshallers to generically pass arbitrary
data through this pointer and then unpack/transform it
somehow when calling the callback -- and language bindings
do this -- but this is unrelated to the signal definition).

If you really mean a signal with more arguments such as
GtkTreeModel::row-changed, then by passing the number of
specific arguments as n_params, their types as `...' (the
list of parameter types) and the corresponding marshaller as
c_marshaller.

> 3) There's no more information about "c_marshaller" parameter,  where
> they are defined or witch I can use on a given situation. Does I need
> to select a marshalled that fits my callback declaration to get the
> correct data?

This is explained in the reference part, section Closures.

Maybe some text should be moved one direction or another?
I'd personally prefer moving most of the implementation
details material from the intro to the reference, but maybe
it's just me...

> 4) On the "Detail" section the text: "Their detailed_signal parameter
> is a string which identifies the name of the signal to connect to",
                                        ^
                                        +------------+
There's something like `and the detail' missing here-+

> then when I create (g_signal_new) a signal name do I need to use a
> form: "signal_name::detail" not just "signal_name"? what about the
> text "signal named notify::cursor_position will actually connect to
> the signal named notify with the cursor_position name", this is
                                                   ^
                                                   +------------------+
> redundant and unclear, what will be the correct name of my signal?  |
                                                                      |
There's something like `detail' missing here--------------------------+

Hopefully it will start making sense then.

And seeing this: The intro should consistently use dashes:
"signal-name", "property-name" (not "signal_name",
"property_name").

Yeti


--
Whatever.