On Mon, 2 Jul 2001, Skip Montanaro wrote:
>
> I'm glad to see James incorporated the gist of my signal- and property-
> listing patches into the latest CVS version of the pygtk2 code. I agree my
> code was in need of some tuning, but I'm a little confused about the names
> and relationship between the pygtk2 functions and their Gtk C API
> counterparts. While it might be nice to have a little higher-level function
> (the new gobject.signal_list_names vs. the combination of
> gobject.signal_name and gobject.signal_list_ids I implemented), someone will
> pay a cost documenting them. Since "g_signal_list_names" is not a function
> in the Gtk/Gobject API, "gobject.signal_list_names" will have to be
> documented. I believe the same holds for the TreeModel API in pygtk2. (It
> seems not to mimic the Gtk C API very closely.)
Well, the gobject module will probably need some python specific
documentation anyway. Many of the concepts need to be put into a python
perspective, and others simply need to be ignored as they are hidden by
the wrapper so a python programmer doesn't need to know about them.
>
> If the Gtk C API is matched as closely as possible the documentation issue
> can be finessed to a great degree by simply pointing people at existing Gtk
> reference documentation (which, I assume, will improve over time) and
> writing a fairly simple mapping manual that explains the conventions used in
> the wrappers (e.g. "Functions named 'g_<whatever>' are exposed as
> 'gobject.<whatever>'"). On the other hand, where I veered off this path by
> wrapping Gtk's g_object_class_list_properties function as simply
> "gobject.list_properties", James changed it back to
> "object_class_list_properties", a name that (to me, anyway) is both a
That should probably be changed. I also need to work out how GParamSpecs
will be handled in python.
> mouthful and seems obtuse (what does the "object_class" part of the name
> mean - why not just "object" or "class" or nothing?). Mapping consistency
> is especially important with Gtk because it's such a large API. Nobody is
> going to want to duplicate the documentation for even 5% Gtk API.
>
> The automagic wrapper stuff based on the gtk.defs file is going to be an
> extremely uniform (and very thin) wrapper around the C API. I think it
> would be beneficial if the stuff that must be done manually tried to be as
> consistent.
I need to extend the documentation generator I wrote to allow merging in
of python specific docs into the final copy. I don't think it will be
possible to produce usable pygtk documentation purely from the C docs.
James.
--
Email: [EMAIL PROTECTED]
WWW: http://www.daa.com.au/~james/
_______________________________________________
pygtk mailing list [EMAIL PROTECTED]
http://www.daa.com.au/mailman/listinfo/pygtk
