Re: [gnome-db] Libgda 3.99.8

[Murray Cumming <murrayc murrayc com>]

On Tue, 2009-01-13 at 08:54 +0100, Vivien Malerba wrote:
> 
> In the meanwhile, if you find any bug or serious API flaw in this
> version, please tell me.

I strongly advise you not to actually release a 4.0.0 until every class
has at least a description in the API. Documenting is the a basic way of
checking that API is sane.

Here are some examples of things that have no description:
GdaThreader: http://bugzilla.gnome.org/show_bug.cgi?id=561175
GdaQuarkList: http://bugzilla.gnome.org/show_bug.cgi?id=561173
I'm sure there are other obscure classes which have no obvious use for
application coders.

Likewise there are functions that seem useless to application coders:
http://bugzilla.gnome.org/show_bug.cgi?id=561178


These (and many others) may be 
a) Totally private API that should not be exposed.
b) API that is only useful when implementing libgda backends. In that
case, they should be documented as such. And ideally they would be
grouped together somehow, though I'm not sure how to do that with
gtk-doc.
c) Useful for application coders. In this case the documentation should
say when we might want to use them.


Fixing this would make the truly useful set of API smaller and therefore
easier to understand.


-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com