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

[Murray Cumming <murrayc murrayc com>]

On Thu, 2010-02-25 at 16:52 +0100, Christian Dywan wrote:
> > 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. 

I don't use this API. I have no idea. I'm not asking why this API is
deprecated. I'm asking for it to be properly documented because it
should be properly documented. And I want this to stop happening.

I see deprecations while updating gtkmm even when I have no great
interest in the particular function. I don't want to carry over this
obviously bad documentation to gtkmm.

If it should never have been used then say so. Try to give some idea
about why it should never have been used. Don't make people guess. But
I'm repeating myself.

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