search

arrow-py / arrow

🏹 Better dates & times for Python
https://arrow.readthedocs.io
Apache License 2.0
8.71k stars 673 forks source link

Audit and improve docstrings #819

Closed jadchaar closed 3 years ago

jadchaar commented 4 years ago

Issue Description

In preparation for the v1.0.0 release, we should audit all the docstrings in the package to make sure they conform to the Sphinx docstring standards.

We should make sure :param: and :return: are included at the very least on every function, including internal utility functions. Type documentation may not be necessary since we will be adding type annotations as part of https://github.com/crsmithdev/arrow/pull/800.

In addition to docstring formatting, we should also audit the docstrings for typos and/or refactor some of the wording to make the interfaces and APIs more clear. Adding a docstring checker like pydocstyle and an automatic docstring formatter could be good additions as well.

systemcatch commented 3 years ago

Hey @jadchaar do you think we still need to do this? I'm happy to give this a go if needed.

jadchaar commented 3 years ago

I think it would be good to go through all the docstrings for typos and make sure they are aligned with new features/functionality introduced over the years. Also, I think we should make sure the input and return types in the docstrings are not redundant now that we are bundling types into our docstrings using the sphinx plugin.