Fix GI transfer mode annotation in ibus_bus_list_*engines() comment.

Fix GI transfer mode annotation in ibus_bus_list_*engines() comment.

See https://bugzilla.gnome.org/show_bug.cgi?id=635248.  Also, do not mark those
functions as "not implemented", since they are apparently implemented.

BUG=none
TEST=manual

[Peng, 2010-11-30 02:59:58]

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h
File src/ibusbus.h (right):

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h#newcode249
src/ibusbus.h:249: * @returns: (transfer container) (element-type
IBusEngineDesc): A List of engines.
What's the meaning of container?

[Daiki Ueno, 2010-11-30 05:55:28]

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h
File src/ibusbus.h (right):

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h#newcode249
src/ibusbus.h:249: * @returns: (transfer container) (element-type
IBusEngineDesc): A List of engines.
On 2010/11/30 02:59:58, Shawn.P.Huang wrote:
> What's the meaning of container?

IIUC, it means that the caller is responsible to release the return container
but not its elements, when releasing the container:

http://live.gnome.org/GObjectIntrospection/Annotations

[Peng, 2010-11-30 06:07:50]

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h
File src/ibusbus.h (right):

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h#newcode249
src/ibusbus.h:249: * @returns: (transfer container) (element-type
IBusEngineDesc): A List of engines.
But in this case, I think both container and elements should be released by
caller. Right?

On 2010/11/30 05:55:28, Daiki Ueno wrote:
> On 2010/11/30 02:59:58, Shawn.P.Huang wrote:
> > What's the meaning of container?
> 
> IIUC, it means that the caller is responsible to release the return container
> but not its elements, when releasing the container:
> 
> http://live.gnome.org/GObjectIntrospection/Annotations

[Daiki Ueno, 2010-11-30 06:35:26]

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h
File src/ibusbus.h (right):

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h#newcode249
src/ibusbus.h:249: * @returns: (transfer container) (element-type
IBusEngineDesc): A List of engines.
On 2010/11/30 06:07:50, Shawn.P.Huang wrote:
> But in this case, I think both container and elements should be released by
> caller. Right?

I also thought that, but asking the Gjs maintainers, there seems to be some
confusion about the memory management semantics.  My current understanding is,
the caller is expected to treat the elements as if they are still "floating" in
the binding language (Gjs here), and not to own them.  Not sure if I can
describe the situation precisely though... See the discussion at:
https://bugzilla.gnome.org/show_bug.cgi?id=635248

[Peng, 2010-12-01 06:05:53]

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h
File src/ibusbus.h (right):

http://codereview.appspot.com/3274044/diff/1/src/ibusbus.h#newcode249
src/ibusbus.h:249: * @returns: (transfer container) (element-type
IBusEngineDesc): A List of engines.
On 2010/11/30 06:35:26, Daiki Ueno wrote:
> On 2010/11/30 06:07:50, Shawn.P.Huang wrote:
> > But in this case, I think both container and elements should be released by
> > caller. Right?
> 
> I also thought that, but asking the Gjs maintainers, there seems to be some
> confusion about the memory management semantics.  My current understanding is,
> the caller is expected to treat the elements as if they are still "floating"
in
> the binding language (Gjs here), and not to own them.  Not sure if I can
> describe the situation precisely though... See the discussion at:
> https://bugzilla.gnome.org/show_bug.cgi?id=635248

I see. After reading the comments within the bugzilla, I am wandering if we
should change the annotation or make the element sink. Which one is more
reasonable?

[Daiki Ueno, 2010-12-02 08:06:57]

On 2010/12/01 06:05:53, Shawn.P.Huang wrote:
> I am wandering if we
> should change the annotation or make the element sink. Which one is more
> reasonable?

It looks to me that changing the annotation is better, since the constructor of
GObject proxy seems to check the latter case specially:
http://git.gnome.org/browse/gjs/tree/gi/object.c#n709

 if (G_IS_INITIALLY_UNOWNED(priv->gobj) &&
     !g_object_is_floating(priv->gobj)) {
     /* GtkWindow does not return a ref to caller of g_object_new.
      * Need a flag in gobject-introspection to tell us this.
      */

[Peng, 2010-12-02 08:19:58]

Thanks. LGTM.
On 2010/12/02 08:06:57, Daiki Ueno wrote:
> On 2010/12/01 06:05:53, Shawn.P.Huang wrote:
> > I am wandering if we
> > should change the annotation or make the element sink. Which one is more
> > reasonable?
> 
> It looks to me that changing the annotation is better, since the constructor
of
> GObject proxy seems to check the latter case specially:
> http://git.gnome.org/browse/gjs/tree/gi/object.c#n709
> 
>  if (G_IS_INITIALLY_UNOWNED(priv->gobj) &&
>      !g_object_is_floating(priv->gobj)) {
>      /* GtkWindow does not return a ref to caller of g_object_new.
>       * Need a flag in gobject-introspection to tell us this.
>       */

[Daiki Ueno, 2010-12-08 08:27:20]

Could you please push this?

[Peng, 2010-12-08 08:39:24]

Done
On 2010/12/08 08:27:20, Daiki Ueno wrote:
> Could you please push this?