It is sometimes suggested, on the other hand, that we shouldn't remove things just to remove them or to "clean up" an interface. As long as it isn't an undue burden to keep the old way around, is there really a need to get rid of it?

That's not to say that the existing token handling in the API couldn't use cleaning up even if the public interface doesn't change. See bug 45199 for more comments on that.

You're an API guy, if you think it's okay, then I say it's okay too.

If we want to keep the handling, then this bug is just about making the documentation use the new way once we stop supporting 1.19.

I should clarify: I haven't really seen opposition to documenting something as deprecated in favor of the new solution, as long as that doesn't mean someone is going to come around and remove it at some point just because it's been deprecated.

(Whatever we do about this, it probably won't be in 1.23 after all; removing milestone.)

In I2793a3f2dd64a4bebb0b4d065e09af1e9f63fb89, action=tokens was deprecated in favor of action=query&meta=tokens, and everything else was also marked as deprecated.