The deprecation docs are fairly terse in terms of which decorator gets applied where/how. @QuLogic had a really nice write up with examples of how to do deprecation in #26865 and I think it'd be great ...