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:
|
class Table: |
|
_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 |
|
def scan( |
|
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: |
|
return DataScan( |
|
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