Re: Prop and Event Conventions (was Re: GNOME::Selector)

[jacob berkman <jacob ximian com>]

On 31 May 2001 21:01:56 -0500, Mike Kestner wrote:
> On 31 May 2001 14:05:32 -0400, Michael Meeks wrote:
> 
> >         bonobo_pbclient_setv (
> >                 obj,
> >                 "mime_types", TC_CORBA_sequence_CORBA_string, &mime,
> 
> Are we adopting some property and event naming and documentation
> conventions for the 2.0 platform?

i don't think we have, but we need to.

> Instead of just whining about it, I'll propose the following as an
> example contract.  It extends the OO service concept to include event
> specification, since they seem to have adopted a specialized listener
> paradigm instead of a generalized ESource.  Whether we ever migrate to
> UNO or not, it seems logical to adopt a similar convention and extend it
> to our needs. I'm not sure where to install this info, with the oaf file
> or the idl files.

i don't know that we need to enforce this in bonobo yet, but this is
essential for API documentation since in fact the API becomes implied by
the interfaces and properties of the objects, rather than their specific
custom API.

> module GNOME { module Draw {
>     service ShapesContract {
>         interface GNOME::Draw::Shapes;
>         interface Bonobo::PropertyBag;
>         interface Bonobo::EventSource;
>         interface Bonobo::PersistStorage;
> 
>         [event] shape_added (ShapeAddedEvent add_event);
>         [event] shape_removed (string shape_name);
> 
>         [property] long ShapeCount; // Just for example
>     };
> }; };

sadly i have nothing to say about this.

> Having something like this, even if it's not hooked into oaf activation
> in 2.0, would help new users avoid the pain of rummaging through code to
> determine the hidden API for components using PBags and ESources.

hmm, i guess i had assumed that documentation of these things would be
required, but i always end up being suprised what doesn't get
documented.

jacob
--
In the afterlife, a cute .signature will only get you so far.