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:

iceberg-python/pyiceberg/table/__init__.py

Lines 1396 to 1410 in e891bcd

	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

iceberg-python/pyiceberg/table/__init__.py

Lines 1447 to 1465 in e891bcd

	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:

• pyiceberg/table:
  • Add Docstrings to pyiceberg/table/__init__.py #1190
  • Add Docstrings to pyiceberg/table/inspect.py #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