beef up docstrings

[jGaboardi]

beef up docstrings

tasks:

• review language for clarity, etc.
• conform to numpydoc standards
• clean up & flesh out Examples
• start performing doctests during CI

xref:

• interest in modernizing? #20
• add type hints #55