consider numpydoc formatting for docstrings

[slivingston]

This API might be easier to understand if it has the standard formatting of the numpy API documentation. As part of this issue, if we are not going to follow numpy doc style, then recommend another.

References

1. https://numpydoc.readthedocs.io/en/latest/format.html
2. https://numpydoc.readthedocs.io/en/latest/example.html