Re: [gtkmm] gtkmm3 speculation: intermediate types.

[Morus Walter <morus walter gmx de>]

Murray Cumming writes:
> By "gtkmm3" I mean "some future API break". That might mean, "gtkmm 2.2"
> or "gtkmm 2.4", and I might not necessarily mean the "next" API break.
> Nothing is going to change soon.
> 
> I'm not very comfortable with our use of intermediate types in the API:
> http://www.gtkmm.org/gtkmm2/docs/tutorial/html/ch03s05.html
> 
> People don't know how to use them unless they read the book or reference
> documentation.
> 
hmm. Having had that problem a few days ago, I would like to note, that
the reference docs aren't very clear about that.

E.g.: let's say one want's to get a list of entries in a combo box.
The reference for Gtk::Combo lists
Glib::ListHandle<Glib::ustring> Gtk::Combo::get_popdown_strings  (     ) 
If one looks up the type Glib::ListHandle<> 
(http://gtkmm.sourceforge.net/gtkmm2/docs/reference/html/classGlib_1_1ListHandle.html)
there is no explanation of what this list handle is meant to be.
There is just the api listing and the first thing one probably sees
is typedef Glib::Container_Helpers::ListHandleIterator< Tr >  iterator&
and 
const_iterator  begin () const
const_iterator  end () const
So to me that was an invitation to use the ListHandle directly.

Perhaps I should have read the tutorial, but even if I had read it,
this wouldn't mean that I would remember that section when I first need
the function.

Maybe there's documentation I didn't see yet, but IMHO you should consider
making this issue more explicit in the api reference docs before changing
the api.

Of course that won't help people not reading any docs at all.

greetings
	Morus