Re: Comment on GNOME/GTK developer docs

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-07-13 at 12:00 +0100, Andrew Jeffries wrote:
> Hi everyone (and thanks to Karderio who pointed me to this list),
> 
> I've had a comment for a while on the GNOME/GTK developer docs but never 
> known where to send it.
> 
> I'm an infrequent GNOME/GTK developer and am by no means an expert.  By 
> the time I've implemented something it's deprecated by GNOME.  I have no 
> issue with this, I'm glad for all your work - but it just leaves me at a 
> dead end.
> 
> For example, in my application I used to use normal windows for 
> messages, then I found GnomeDialogs which were much easier.  I went back 
> to look at a bit of documentation for GnomeDialog as I've found a 
> problem in my app and came across the following:
> 
> "GnomeDialog is deprecated and should not be used in newly-written code."
> http://developer.gnome.org/doc/API/2.0/libgnomeui/GnomeDialog.html#GnomeDialog-struct
> 
> So, great, you've come up with a new architecture for doing this sort of 
> thing.  Cool!  But what is it?
> 
> When I say this I don't mean "can someone tell me what the replacement 
> for GnomeDialog is" - I mean "could the docs not say XYZ is deprecated 
> and should not be used in newly-written code; instead use XYZng, more 
> information _here_".

Unfortunately, the libgnomeui documentation was never really
very good, and as we deprecate more and more of libgnomeui,
nobody's making the documentation any better.  (For reference,
stuff that's deprecated in libgnomeui has probably found a new
home in GTK+.)

If you look at the GTK+ documentation, you'll notice that most
deprecated interfaces *do* say what to use instead.  There are
likely a few exceptions, but the rule is that we document what
deprecated interfaces are replaced with.

We should do a much better job though.

--
Shaun