[Gtk-sharp-list] Full documentation by 1.0

Miguel de Icaza miguel@ximian.com
Tue, 22 Jun 2004 15:55:45 -0400


Hello,

> 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 agree with you 100%.

I have been trying to push for documentation for at least a year now,
with various degrees of success.  We even got Monodoc to have a
built-in editing facility so folks could contribute without having to
learn too much about CVS, but it has only resulted in marginal
contributions.

Could I convince you to contribute to the Gdk.Pixdata classes that you
just learned how to use the hard way?

Miguel