fixed docstrings (including deprecation details)