Deprecation, consistency and docstrings for core methods #3128
This PR is an attempt to make the core API more consistent by ensuring that method signatures are consistent, deprecating methods which are not useful or duplicative and add consistent docstrings throughout.
As a first step I added a
Newly deprecated methods
These will go through a whole deprecation cycle, i.e. we will announce them as deprecated in the release notes, then disable the
Methods made more consistent
There are still a number of data conversion methods that have some usefulness and are used throughout the code and therefore probably require a longer deprecation cycle if we were to decide to remove them:
Methods we should consider introducing as replacements
A number of items have been deprecated for a long time but were never removed
This PR adjusts the inheritance hierarchies, introducing a new category of elements with
There are now the following general classes of elements:
Classes that have had docstrings added:
All the suggested deprecations you describe seem very reasonable though (as I mention in #2322) I am not very enthusiastic about these giant docstrings. Are there any tools to validate this format? Check the actual signature matches what is declared in the docstring at least?
Ok, I've found myself an emacs code folding solution I can use which makes me happier with these docstrings (at least from a developer perspective). I'll just fold away these docstrings in the files that have them if they stop me seeing the code.
As for Google versus NumPy style, here are my thoughts:
I personally doubt anyone would find the google style confusing even if they haven't seen it before. This means that on balance, I vote for the google style.
I'd be happy to switch to Google style, it's what bokeh uses and it is indeed a bit more compact. That said it's an even larger job to convert to that style because the first line with the quotes is expected to provide a summary, something we have never done, e.g.:
Unfortunately, IPython only scans the first non-empty line which means you need to insert the signature on the initial line with the short description. At least IPython does seem to scan the whole line so we could append the signature after the short description.
I'm not sure whether tools that use docstrings (e.g sphinx) will pick up on dynamically mutated docstrings (one option is to try to only update docstrings in an ipython context, e.g see the suggestion in holoviz/param#305). One thing that we cannot really fix is the mess a user would see calling