Provide decorator for replaced parameters - #5208

This PR derives from #5171, where the discussion lead to a decorator to handle renamed keyword parameters. I felt that changes were large enough that the decorator part should be its own PR, since it has little to do with the replacement of the clobber keyword parameter.
If people deem otherwise, this PR can simply be closed and I'll move the decorator to #5171.
@MSeifert04 and @pllim may be interested in this PR, as they were involved in #5171. With credits to MSeifert04, who came up with an initial implementation and may have more to add.

NB: naming and wording may want some change. E.g., "renamed" may be better than "replaced".

@evertrol , separate PR is fine, as long as we merge this first, and then update #5171 to use it. Thanks!

NB: naming and wording may want some change. E.g., "renamed" may be better than "replaced".

I agree, rename sounds better. For replace I think about changing the order rather than the name itself.

@evertrol I also had a commit for the decorator (I was about to make a PR when I realized you already opened one). If you want you can have a look: https://github.com/MSeifert04/astropy/commit/b0d65c6bff58f5a38aaf570cfc7200345b4e24c6

@MSeifert04 If you like, I'm happy to withdraw this PR in place of yours, since you came up with the decorator in the first place. Otherwise, I'll incorporate parts of your PR into mine; the arg_in_kwargs seems useful. Or, as suggested before, you can create a PR against this PR.
I'm not really in favour of a relax option though: I can't think of a case where it's useful to allow both the new and deprecated argument to be used. Mostly where a user updates the function call, but forgets to remove the old argument; in which case it seems more logical to inform the user by raising a TypeError, similar to calling the function with an incorrect argument.

@evertrol I know at least one place where relax would be fine: https://github.com/astropy/astropy/blob/master/astropy/stats/sigma_clipping.py#L22 (which is essentially the decorator with relax). I agree that it's not useful in most of the cases but at least it offers the freedom.

I'll don't know if it's easy to make a PR against your branch because they now differ in some aspects. I will take a look later.

@evertrol , @MSeifert04 -- Whichever of you end up with the final PR, you can still credit each other by manually changing the commit author via git commit --amend --author "New Author Name <email>"

@pllim Where do you always get these handy informations? I never heard of manually changing the author of the commit 😮 But wouldn't it completly replace the person doing the commit?

I actually don't know what the best way to proceed would be. The decorators behave similar but each has some unique features which would be nice to have in the other one.

@MSeifert04 , I did that in #3094 . If you look at the commits there, you will see some "such-and-such commited with such-and-such" entries.

@MSeifert04:

Where do you always get these handy informations? I never heard of manually changing the author of the commit 😮 But wouldn't it completly replace the person doing the commit?

It's usually described in git tutorials under "Rewrite history" or similar sections. However you're right, doing what @pllim suggests above completely changes the author, and that's shows up in the git log, etc. However there is also another field: commiter that becomes the person who actually makes the commit (that's why there are two names in those commits in #3094, but only one is the author).
Same happens when you cherry-pick, and think it's clearer and preferable that way, rather than adding names to commits that actually wasn't made by said person.

Needless to say git and git history are thus not suitable for fair credit sharing for e.g. pair coding or team brainstorming, etc.

@MSeifert04 The sigma_clip example is probably where I would prefer to raise a TypeError, so it's really about how backward compatible you'd like to be there (how much user base currently relies on this particular behaviour, using both keywords and ignoring the warning?).
A PR against my branch will require some copy-pasting, as it indeed is unlikely to merge properly with your commit. But I'd be totally fine with having this PR closed and using yours instead. (After all, I'm just after renaming clobber to overwrite.)