Mathewpeterson/add more deprecation

@dianakhuang @dmitchell @cpennington Review?
s/an/a/
Also please use the `:class:` etc markup used in other docstrings.