Skip to content

DOCS: Missing Docstrings in public API #1056

Open
@sungwy

Description

@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:

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:

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions