BUG,ENH: make deprecated decorator work (and more flexibly)

[efiring]

1. Fix the bug in which _generate_deprecation_message was failing
   to substitute arguments for string formats in user-supplied
   message argument.
2. Make internal naming consistent: the argument is "name", and
   now the string format specifications also use "name", not "func".
3. Add an "addendum" kwarg so that the standard message, with its
   convenient argument substitution, can be used, and additional
   explanation can be appended as a plain text string.

Closes #7647.

[NelleV]

My two cents on our deprecation functions is that they are extremely complicated to use and hard to predict what the deprecation message is going to be. Is there a way to simplify that?

[efiring]

This PR should make it quite a bit easier; in most cases, just leave all kwargs but the last as defaults (unless "alternative" can be specified) and put additional information in "addendum". That way, the message always starts out with the standard pattern, automatically identifying what is being deprecated and when.

Also, part of the difficulty you experienced might have been because the behavior did not match the documentation--there was a huge bug, which this PR fixes.

Additional steps to make it easier would be adding full examples to the documentation, showing exactly what happens by default, and with common combinations of kwargs.

[NelleV]

My strategy is currently to git grep and see what people do or to provide explicitely the deprecation message :)

[tacaswell]

@amueller 's https://github.com/amueller/futurepast might be interesting to look at here as well.

[amueller]

unfortunately futurepast is not really ready for consumption yet. I'd be happy to check out what needs to be done to make your use-cases more simple. That library needs like a week of crunch-time then it should be ok lol

[efiring]

I think the system we have right now, with the present PR merged, serves our purposes well.