Re: When deprecating, always say what the replacement is.

[Christian Dywan <christian lanedo com>]

Am Tue, 23 Feb 2010 23:13:51 +0100
schrieb Murray Cumming <murrayc murrayc com>:

> On Tue, 2010-02-23 at 22:36 +0100, Michael Natterer wrote:
> > On Tue, 2010-02-23 at 19:59 +0100, Murray Cumming wrote:
> > > No, "Deprecated: 2.20: Do not use it." is not good enough.
> > 
> > As a matter of fact, it is. There is not supposed to be any
> > replacement for the stuff that says "Do not use it". Everything
> > that has a replacement is however documented.
> 
> But "Do not use it" does not even make that clear. The reader has no
> idea whether it is something that should never have been used (and why
> not) or something that has a replacement. It shouldn't take much
> empathy to realize that, or to realize that documentation _must_ have
> a problem if someone says it's unclear. We can do better.

The few "Don't use it" comments in GTK+ usually indicate that it is
questionable why someone would try to use a function in the first place.

In this case I don't know what someone would use flags for. If you need
to test a value such as visibility or sensitivity, you normally use the
specific macros. As far as I'm aware at least.

Can you give an example? Then I'd say pointing that out certainly can't
hurt.

ciao,
    Christian