Re: Milestones document

[Derek Simkowiak <dereks kd-dev com>]

> >  However, I think the feeling is that gnome-libs is almost ready. 
> 
> We cannot release it without complete API reference documentation.  Period.

     Federico,
	Thank you!  I've been fighting undocumented Gtk+ widgets lately
and surfing through source code to figure out what a function does is
simply not an acceptable requirement for an easy-to-use library.

	As Open Source coders, we may be used to using the source as
documentation, but it's a huge timesink and people coming from other
platforms will give up quickly if the API is not completely, 100%,
documented.

	I've seen somebody using Microsoft Visual C++ and all the
documentation is built-in to the IDE, cross-referenced and hotlinked.  He
was trying to analyze a bug and it was impressive how quickly he could fly
through the documentation to get the answers he needed.

	Of course, the Gtk+ reference HTML pages are a good start, but
there are far too many undocumented widgets.  If it were up to me, every
widget/API would have complete descriptions, a list of pitfalls and
common problems, along with an illustrative example.

	[Okay, I'll get off the soapbox now...]


--Derek