Consistent functions and method docstring style

HoloViews is built on param which has the great advantage of providing a neat way of documenting the parameters of classes. While this is a great way to structure class level parameters, it does not provide anything that documents methods and functions. The current state of the docstrings on methods and functions in HoloViews is therefore what I’d call highly inconsistent and therefore quite frustrating for users.

While a large paragraph explaining what the method does is often sensible, docstrings are far more commonly used to quickly figure out what that one particular argument was called, what options it supports and what type it expects. I therefore think there is a pretty desperate need for us to standardize on some standard docstring format at least for functions and methods.

I’d be strongly in favor of moving to simple NumPy-style docstrings with sections for Parameters and Return values:

Some description of the function or method.

Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)

Returns
-------
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.

Readability of this is infinitely better than having to scan a large paragraph for the argument that I care about. After 1.10 is released I’d like to start a systematic review of all docstrings (many of which are hopelessly outdated) and upgrade them to a consistent style. I have no strong preference for any specific format but think that explicitly listing the arguments and return values will result in a much improved user experience and help us consider and address current API inconsistencies.

[philippjfr]

This is more important for user code than developer code.

Yes, I’d suggest we do it incrementally starting with some of the core classes like Dimensioned, LabelledData, NdMapping, HoloMap, DynamicMap, Element and Dataset.

[philippjfr]

Since we’ve not made a decision and started the conversion I don’t think we need this issue anymore.