search

apache / iceberg-python

Apache PyIceberg
https://py.iceberg.apache.org/
Apache License 2.0
467 stars 169 forks source link

DOCS: Missing Docstrings in public API #1056

Open sungwy opened 3 months ago

sungwy commented 3 months ago

Feature Request / Improvement

As we prepare for a major release, I think it would be great to hold our public APIs to a higher standard of documentation.

Many popular public classes, methods and functions are currently missing docstrings.

Here are some examples: https://github.com/apache/iceberg-python/blob/e891bcddb1584c6b7a35b61537ab5802b514ec6d/pyiceberg/table/__init__.py#L1396-L1410

https://github.com/apache/iceberg-python/blob/e891bcddb1584c6b7a35b61537ab5802b514ec6d/pyiceberg/table/__init__.py#L1447-L1465

I think that the Google style guide for Comments and Docstrings is a good start, as it has a easily human-readable format that includes description, args, returns and exceptions that is also Sphinx parse-able (if we ever decide to autogenerate API docs that way in the future)

TODO:

askalik commented 1 month ago

Can I try this one? Just for clarification it looks like #1190 is completed, but #1191 is needed?

sungwy commented 1 month ago

Hi @askalik - yes, that'll be amazing! If you leave a comment on #1191 I can get that assigned to you