Re: [gtkmm] gtkmm3 speculation: intermediate types.

[murrayc t-online de (Murray Cumming)]

On Mon, 2002-11-04 at 14:47, Carl Nygard wrote:
> On Mon, 2002-11-04 at 06:45, Murray Cumming wrote:
> > 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
> > 
> 
> I apologize for not having time enough to contribute code, all I can do
> is contribute my opinions;)
> 
> > People don't know how to use them unless they read the book or reference
> > documentation.
> 
> This always strikes me as an oxymoron-ish argument.  If you want it to
> be easy enough to use without docs, why do you provide docs?

I think the ideal API, like the ideal UI, should not require docs, or it
should be obvious when you need to look at the docs. The reason I don't
like the look of the intermediate types is that it looks at first as if
you should just use them directly.

>   I know I
> can't use Gtk+ just by looking at functions and arguments, I need the
> docs.  So why worry about it?

Well that's one reason why people like gtkmm. gtkmm has a clearer API,
without the docs, than GTK+.

>   They're already digging in the docs for
> how to use manage properly...;)

No part of the API involves Gtk::manage(), you would only want to know
about it if you've seen example code, or you're looking for that kind of
thing.

> > I think their advantage (You can choose whether to use a list, vector,
> > or whatever, instead of us choosing for you) doesn't outweigh the
> > disadvantage (they make the API less clear, and people might we're
> > stupid enough to implement non-standard containers). Please discuss.
> 
> Docs are available to show how to use the API, and to explain the merits
> of the API.  (Non)existance of docs should not be used as an argument in
> a technical decision.  Ultimately, it's the technical decisions that
> attract or repel people using the library (vis Qt moc/Qstring vs. Gtkmm
> STL/SigC/manage), not whether they can figure something out by looking
> at the function signature.

API clarity is important, particularly if the confusion is never
resolved. People rarely look at docs and I'd prefer to deal with that
reality.

> I'm not saying clarity and ease of use isn't important, I'm just saying
> don't take it to extremes and let it unduly influence a technical design
> decision.

I think I'm persuaded by Daniel's arguments anyway, but I wanted to know
how other people felt about it.

-- 
Murray Cumming
murray usa net
www.murrayc.com