Re: [sigc] Libsigc++ glossary typos and possible clarifications.

["Murray Cumming" <murrayc murrayc com>]

>
> Hi, all.
>
> I was looking at the libsigc++ glossary page:
>
>   http://libsigc.sourceforge.net/glossary.shtml
>
> Is there a specific someone who maintains this page and to whom I can
> send email directly?  Or is it more appropriate for me to send mail to
> the whole mailing list?

Please treat it like any other patch - add it to bugzilla and discuss it
here if you are not sure what to do.

The website is still in the libsigc++-1.2 module, in docs/website. Please
just patch that. Instructions for patching are here:
http://www.gtkmm.org/bugs.shtml

> Libsigc++ looks pretty cool to me, and I would like to use it and
> encourage others to use it as well.  But an obstacle to people adopting
> a new library can be a steep learning curve made worse by unclear and/or
> messy documentation.

Yes, some of the documentation is quite old, and refers to libsigc++-1.2
stuff, instead of the new 2.0 API. And Karl Nelson was never good at
writing high-level docs.

I would remove all of the libsigc++-1.2 documentation that is listed on
the site. It can live in libsigc++-1.2 in cvs in case anybody wants to see
it.

>  So, to clarify things, maybe some or all of the
> following things in the glossary page should be addressed:
>
> adaptor:   "Function" --> "A function"
> adaptor:   "slots"  -->  "slot's"
>
> call: "Process" --> "The process"
>
> callback:  how's about "A function (with an associated structure and set
> of arguments) which can be called and which in turn may call other
> functions or methods."?  Is this what was meant?

I would say "A function or a member function which will be called when a
signal is emitted. A slot specifies the callback and any extra data, such
as  the object instance, and extra parameters.".

> connect: "Process"  -->  "The process"
>
> connect:  what does it mean to destroy a slot?  A slot is defined later
> as a safe version of a callback.  Why should a callback be destroyed
> when it is put in a callback container (i.e. into a signal?)

This seems useless. I'd just say "The process of specifying the callback
that will be called when the signal is emitted.".

> emit:  what does it mean to "invoke a signal"?  Below, a signal is
> defined as a container.  What does it mean to invoke a container?

I think "When a signal is emitted, the connected slots will be called."
should be enough.

> marshaller:  "Structure"  -->  "A structure"
> marshaller:  what is a "multi-callback"?

I'd say

When a signal has a return value, and several slots are connected to that
signal, each one returning a value, then a marshaller chooses one single
return value.

> reference:  "attempts to prevent that object from deleting"??  This is
> not clear.  Are you talking about the simple reference mechanism built
> into C++?  If so, that doesn't have anything to do with deleting.  Are
> you talking about reference counting with smart pointers (as in Meyers's
> "Effective C++")?  That might make more sense, but is still not clear.

Let's remove this. It's not relevant to the libsigc++ 2 API and was not
very interesting in libsigc++ 1.2.

> signal:  "Container" --> "A container"
> signal: "emited" --> "emitted".
> signal: "Container for slots which can be emited"??  What can be
> emitted?  The Container?  If so, what does it mean for a container to be
> emitted?  The slots?  But the slot definition doesn't explain what it
> means to emit a slot, and the emit definition talks about invoking a
> signal, which is a circular definition.

How about:
"
An object to which callback slots can be connected. When the signal is
emitted, each callback will be invoked. The signal and the connected slots
have a specific return type and parameter types.
"

I think it's OK for the glossary to refer to itself. It's just a glossary,
and people should read the tutorial-style documentation to really
understand:
http://libsigc.sourceforge.net/libsigc1_2/manual/html/

However that needs to be updated for libsigc++ 2.0. That's not much work.

> signal handler: What kind of function connected to a signal?  Do you
> mean a slot?  Is the signal handler the (safe) callback?

I would just say "Another name for a callback.".

> signature:  "function" --> "function."
>
> slot: "Safe" --> "A safe"

As for callback, I'd say "A slot specifies the callback and any extra
data, such as  the object instance, and extra parameters."

Ideally, these would link to useful parts of the API reference, but we can
try to do that later. Actually, the reference documentation probably
already has similar text describing these "modules", on the module pages:
http://libsigc.sourceforge.net/libsigc2/docs/reference/html/modules.html

Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com