Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker <brobecker at gnat dot com>]

>   Erm... things that get deprecated don't often get un-deprecated, do they?

No, they are supposed to disappear over time :-).

> Wouldn't it largely be a matter of just adding a couple of lines each time
> something gets deprecated, just enough to say "All this stuff is now
> replaced by the new XXXX mechanism; use XXXXX_do_whatever in place of
> deprecated_OLDXXXXXX_do_somethingelse, or see gdb-XXXXX.h for more
> information."  Or words to that effect.

But why is it better to write this in a document that's separate from
the code, instead of directly putting this in the code in an absolutely
clear way? If you rename the entity that's deprecated from "entity" to
"deprecated_entity", then it's pretty clear that you should no longer
be using it in new code, or else have a good reason for still using it.
Then if you want to know more, you just go to where the entity is
defined, and look at the comments there. If you put this in some
written document separate from the code, then you have to: change one
other file, ask for review from a different maintainer, then commit.
And then, you have to constantly remember from the doc which entities
are deprecated when you write code and when you review a change.
And then you have to remove it from the doc when the entity is finaly
removed.

In any case, the main debate between Andrew and Eli is not about where
to put the information, but *when* it is ok to decide that something
is declared deprecated.

-- 
Joel