documenting data attributes better?

[Skip Montanaro <montanaro tttech com>]

I don't know if this is a gtk-doc problem or a developer problem, so...

Today on comp.lang.python someone asked how to get the number of rows in a
GtkCList.  Having never used it, I RTFM'd.  I read and fiddled and generally
came to the conclusion that you had to just keep track of that information
as you added data to the widget, because I just couldn't find anything
documented.  Someone then posted that you simply access the rows attribute
of the widget.  Ah!  Why didn't I think of that?  Well, as it turns out,
it's not documented.  In fact, the documentation doesn't list any of the
GtkCList data members and states:

    struct GtkCList; This is the embodiment of the GtkCList widget.  This
    structure contains only private data, and should be accessed only via
    the CList API.

Now, I realize that GtkCList is on the way out, but I'm pretty sure I've
encountered this with other valid-in-2.0 widgets.

Can this be (or is this being) addressed for the 2.0 release?

Thx,

-- 
Skip Montanaro (skip pobox com)
http://www.mojam.com/
http://www.musi-cal.com/