DOCS: Missing Docstrings in public API

[sungwy]

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:

• pyiceberg/table:
  • [x] #1190
  • [ ] #1191
  • [ ] ...

[geekusa33]

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

[sungwy]

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

[github-actions[bot]]

This issue has been automatically marked as stale because it has been open for 180 days with no activity. It will be closed in next 14 days if no further activity occurs. To permanently prevent this issue from being considered stale, add the label 'not-stale', but commenting on the issue is preferred when possible.