Conflicting recommendations about using GTK_BIN(widget)->child in Gtk+ documentation

[Kalle Vahlman <kalle vahlman gmail com>]

Hi all.

I noticed that there is a conflict in what GtkBin docs say:

http://developer.gnome.org/doc/API/2.0/gtk/GtkBin.html#GtkBin-struct
"
The GtkBin-struct struct contains the following fields. (These fields
should be considered read-only. They should never be set by an
application.)

GtkWidget *child; 	the child widget.
"

and what the GtkComboBoxEntry docs say:

http://developer.gnome.org/doc/API/2.0/gtk/GtkComboBoxEntry.html#gtk-combo-box-entry-new-with-model
"
You can get the GtkEntry from a GtkComboBoxEntry using GTK_ENTRY
(GTK_BIN (combo_box_entry)->child).
"

So either the GtkBin or GtkComboBoxEntry docs needs to be changed in
this regard.

Considerations:

1) GTK_BIN(widget)->child is officially available as
gtk_bin_get_child(), so it's not like it would be required to retrieve
the entry from a GtkComboBoxEntry.

2) GTK_BIN(widget)->child is insanely more pleasant to use in code,
and a little more object oriented than gtk_bin_get_child() (which is
in my books always a good thing :)

3) Use of public widget struct members are used succesfully with
GtkDialog (->vbox and ->action_area), so it's not like doing something
new.

4) Given the GtkComboBoxEntry docs recommendation and personal
observations, GTK_BIN(widget)->child is a common trait so it can't
really be considered as a contender for change in any way without
breaking a multitude of code. No point in trying to hide it instead of
embracing it, right?-)

So my score is on the side of admitting GtkBin->child as a public
member in the docs, what's yours?

--
Kalle Vahlman, zuh iki fi
Powered by http://movial.fi
Interesting stuff at http://syslog.movial.fi