[Gtk-sharp-list] Full documentation by 1.0

Brian Kerrick Nickel kerrick@cox.net
Mon, 21 Jun 2004 15:50:44 -0700


After wasting hours of my life trying to figure out Gdk.Pixdata.
Serialize, it's become apparent to me that before Gtk# 1.0 comes out,
the entire thing needs to be carefully documented for two reasons:

     1. No matter how good, simple, an easy to use an API is, if the
        only explanation as to what the function does it it's variable
        names, you're going to end up with lost and confused developers,
        such as myself.
     2. The API has lots of little bugs. Documenting the API has forced
        me to look at the generated source and the gtk+ docs many times
        and when I have, I've found several functions passing or
        returning the wrong types, making them virtually worthless.
        Documenting is the second best way to find these bugs, the first
        being using the functions, but that could be difficult if they
        aren't documented :)


I know first hand how boring and daunting documenting dozens of obscure
functions can be, but it is really necessary to make Gtk# an easy-to-
use, bug free API, which is the whole point of the thing. I'm new here
so I don't know if a similar initiative is under way, but I would like
to get a team of whoever is willing to go through the docs making sure
every function, property, parameter, return value, et al both has a
description and uses the right type. This will mean reviewing the source
and many trips to http://developer.gnome.org/docs/API/

After that, I'd ideally like to see a bunch of tested and easy to read
code examples.


Anyway, that's my two cents on the issue,
Brian Kerrick Nickel