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

[github-actions]

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.