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:
| classTable: |
| _identifier: Identifier=Field() |
| metadata: TableMetadata |
| metadata_location: str=Field() |
| io: FileIO |
| catalog: Catalog |
| |
| def__init__( |
| self, identifier: Identifier, metadata: TableMetadata, metadata_location: str, io: FileIO, catalog: Catalog |
| ) ->None: |
| self._identifier=identifier |
| self.metadata=metadata |
| self.metadata_location=metadata_location |
| self.io=io |
| self.catalog=catalog |
| defscan( |
| self, |
| row_filter: Union[str, BooleanExpression] =ALWAYS_TRUE, |
| selected_fields: Tuple[str, ...] = ("*",), |
| case_sensitive: bool=True, |
| snapshot_id: Optional[int] =None, |
| options: Properties=EMPTY_DICT, |
| limit: Optional[int] =None, |
| ) ->DataScan: |
| returnDataScan( |
| table_metadata=self.metadata, |
| io=self.io, |
| row_filter=row_filter, |
| selected_fields=selected_fields, |
| case_sensitive=case_sensitive, |
| snapshot_id=snapshot_id, |
| options=options, |
| limit=limit, |
| ) |
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:
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:
iceberg-python/pyiceberg/table/__init__.py
Lines 1396 to 1410 in e891bcd
iceberg-python/pyiceberg/table/__init__.py
Lines 1447 to 1465 in e891bcd
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/__init__.py#1190pyiceberg/table/inspect.py#1191