docs: Document more return types (#1381)

docs/requirements-docs.txt

@@ -1,3 +1,4 @@
+black  # required by mkdocstrings_handlers
 jinja2
 duckdb
 markdown-exec[ansi]

narwhals/_arrow/dataframe.py

@@ -614,11 +614,8 @@ def unique(
         keep: Literal["any", "first", "last", "none"] = "any",
         maintain_order: bool = False,
     ) -> Self:
-        """
-        NOTE:
-            The param `maintain_order` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param `maintain_order` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         import numpy as np  # ignore-banned-import
         import pyarrow as pa  # ignore-banned-import()
         import pyarrow.compute as pc  # ignore-banned-import()

narwhals/_arrow/series.py

@@ -518,7 +518,7 @@ def value_counts(
         name: str | None = None,
         normalize: bool = False,
     ) -> ArrowDataFrame:
-        """Parallel is unused, exists for compatibility"""
+        """Parallel is unused, exists for compatibility."""
         import pyarrow as pa  # ignore-banned-import()
         import pyarrow.compute as pc  # ignore-banned-import()
 
@@ -700,11 +700,8 @@ def is_sorted(self: Self, *, descending: bool = False) -> bool:
             return pc.all(pc.less_equal(ser[:-1], ser[1:]))  # type: ignore[no-any-return]
 
     def unique(self: Self, *, maintain_order: bool = False) -> ArrowSeries:
-        """
-        NOTE:
-            The param `maintain_order` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param `maintain_order` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         import pyarrow.compute as pc  # ignore-banned-import()
 
         return self._from_native_series(pc.unique(self._native_series))

narwhals/_arrow/utils.py

@@ -197,8 +197,7 @@ def validate_dataframe_comparand(
 
 
 def horizontal_concat(dfs: list[Any]) -> Any:
-    """
-    Concatenate (native) DataFrames horizontally.
+    """Concatenate (native) DataFrames horizontally.
 
     Should be in namespace.
     """
@@ -219,8 +218,7 @@ def horizontal_concat(dfs: list[Any]) -> Any:
 
 
 def vertical_concat(dfs: list[Any]) -> Any:
-    """
-    Concatenate (native) DataFrames vertically.
+    """Concatenate (native) DataFrames vertically.
 
     Should be in namespace.
     """

narwhals/_dask/dataframe.py

@@ -198,11 +198,8 @@ def unique(
         keep: Literal["any", "first", "last", "none"] = "any",
         maintain_order: bool = False,
     ) -> Self:
-        """
-        NOTE:
-            The param `maintain_order` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param `maintain_order` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         subset = flatten(subset) if subset else None
         native_frame = self._native_frame
         if keep == "none":

narwhals/_dask/group_by.py

@@ -97,8 +97,7 @@ def agg_dask(
     keys: list[str],
     from_dataframe: Callable[[Any], DaskLazyFrame],
 ) -> DaskLazyFrame:
-    """
-    This should be the fastpath, but cuDF is too far behind to use it.
+    """This should be the fastpath, but cuDF is too far behind to use it.
 
     - https://github.com/rapidsai/cudf/issues/15118
     - https://github.com/rapidsai/cudf/issues/15084

narwhals/_expression_parsing.py

@@ -155,8 +155,10 @@ def parse_into_exprs(
     namespace: CompliantNamespace,
     **named_exprs: IntoCompliantExpr,
 ) -> ListOfCompliantExpr:
-    """Parse each input as an expression (if it's not already one). See `parse_into_expr` for
-    more details."""
+    """Parse each input as an expression (if it's not already one).
+
+    See `parse_into_expr` for more details.
+    """
     return [parse_into_expr(into_expr, namespace=namespace) for into_expr in exprs] + [
         parse_into_expr(expr, namespace=namespace).alias(name)
         for name, expr in named_exprs.items()
@@ -209,12 +211,13 @@ def reuse_series_implementation(
     If Series.foo is already defined, and we'd like Expr.foo to be the same, we can
     leverage this method to do that for us.
 
-    Arguments
+    Arguments:
         expr: expression object.
         attr: name of method.
         returns_scalar: whether the Series version returns a scalar. In this case,
             the expression version should return a 1-row Series.
-        args, kwargs: arguments and keyword arguments to pass to function.
+        args: arguments to pass to function.
+        kwargs: keyword arguments to pass to function.
     """
     plx = expr.__narwhals_namespace__()
 
@@ -278,9 +281,8 @@ def func(df: CompliantDataFrame) -> list[CompliantSeries]:
 def reuse_series_namespace_implementation(
     expr: CompliantExprT, series_namespace: str, attr: str, *args: Any, **kwargs: Any
 ) -> CompliantExprT:
-    """Just like `reuse_series_implementation`, but for e.g. `Expr.dt.foo` instead
-    of `Expr.foo`.
-    """
+    # Just like `reuse_series_implementation`, but for e.g. `Expr.dt.foo` instead
+    # of `Expr.foo`.
     plx = expr.__narwhals_namespace__()
     return plx._create_expr_from_callable(  # type: ignore[return-value]
         lambda df: [
@@ -295,16 +297,16 @@ def reuse_series_namespace_implementation(
 
 
 def is_simple_aggregation(expr: CompliantExpr) -> bool:
-    """
-    Check if expr is a very simple one, such as:
+    """Check if expr is a very simple one.
 
-    - nw.col('a').mean()  # depth 1
-    - nw.mean('a')  # depth 1
-    - nw.len()  # depth 0
+    Examples:
+        - nw.col('a').mean()  # depth 1
+        - nw.mean('a')  # depth 1
+        - nw.len()  # depth 0
 
     as opposed to, say
 
-    - nw.col('a').filter(nw.col('b')>nw.col('c')).max()
+        - nw.col('a').filter(nw.col('b')>nw.col('c')).max()
 
     because then, we can use a fastpath in pandas.
     """
@@ -324,7 +326,7 @@ def combine_root_names(parsed_exprs: Sequence[CompliantExpr]) -> list[str] | Non
 
 
 def reduce_output_names(parsed_exprs: Sequence[CompliantExpr]) -> list[str] | None:
-    """Returns the left-most output name"""
+    """Returns the left-most output name."""
     return (
         parsed_exprs[0]._output_names[:1]
         if parsed_exprs[0]._output_names is not None

narwhals/_pandas_like/dataframe.py

@@ -301,11 +301,8 @@ def iter_rows(
         named: bool = False,
         buffer_size: int = 512,
     ) -> Iterator[list[tuple[Any, ...]]] | Iterator[list[dict[str, Any]]]:
-        """
-        NOTE:
-            The param ``buffer_size`` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param ``buffer_size`` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         if not named:
             yield from self._native_frame.itertuples(index=False, name=None)
         else:
@@ -667,11 +664,8 @@ def unique(
         keep: Literal["any", "first", "last", "none"] = "any",
         maintain_order: bool = False,
     ) -> Self:
-        """
-        NOTE:
-            The param `maintain_order` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param `maintain_order` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         mapped_keep = {"none": False, "any": "first"}.get(keep, keep)
         subset = flatten(subset) if subset else None
         return self._from_native_frame(

narwhals/_pandas_like/group_by.py

@@ -136,8 +136,7 @@ def agg_pandas(  # noqa: PLR0915
     dataframe_is_empty: bool,
     native_namespace: Any,
 ) -> PandasLikeDataFrame:
-    """
-    This should be the fastpath, but cuDF is too far behind to use it.
+    """This should be the fastpath, but cuDF is too far behind to use it.
 
     - https://github.com/rapidsai/cudf/issues/15118
     - https://github.com/rapidsai/cudf/issues/15084

narwhals/_pandas_like/series.py

@@ -498,11 +498,8 @@ def cum_sum(self) -> PandasLikeSeries:
         return self._from_native_series(self._native_series.cumsum())
 
     def unique(self, *, maintain_order: bool = False) -> PandasLikeSeries:
-        """
-        NOTE:
-            The param `maintain_order` is only here for compatibility with the Polars API
-            and has no effect on the output.
-        """
+        # The param `maintain_order` is only here for compatibility with the Polars API
+        # and has no effect on the output.
         return self._from_native_series(
             self._native_series.__class__(
                 self._native_series.unique(), name=self._native_series.name
@@ -653,7 +650,7 @@ def value_counts(
         name: str | None = None,
         normalize: bool = False,
     ) -> PandasLikeDataFrame:
-        """Parallel is unused, exists for compatibility"""
+        """Parallel is unused, exists for compatibility."""
         from narwhals._pandas_like.dataframe import PandasLikeDataFrame
 
         index_name_ = "index" if self._name is None else self._name

narwhals/_pandas_like/utils.py

@@ -171,8 +171,7 @@ def create_compliant_series(
 def horizontal_concat(
     dfs: list[Any], *, implementation: Implementation, backend_version: tuple[int, ...]
 ) -> Any:
-    """
-    Concatenate (native) DataFrames horizontally.
+    """Concatenate (native) DataFrames horizontally.
 
     Should be in namespace.
     """
@@ -192,8 +191,7 @@ def horizontal_concat(
 def vertical_concat(
     dfs: list[Any], *, implementation: Implementation, backend_version: tuple[int, ...]
 ) -> Any:
-    """
-    Concatenate (native) DataFrames vertically.
+    """Concatenate (native) DataFrames vertically.
 
     Should be in namespace.
     """
@@ -644,8 +642,11 @@ def select_columns_by_name(
     backend_version: tuple[int, ...],
     implementation: Implementation,
 ) -> T:
-    """Select columns by name. Prefer this over `df.loc[:, column_names]` as it's
-    generally more performant."""
+    """Select columns by name.
+
+    Prefer this over `df.loc[:, column_names]` as it's
+    generally more performant.
+    """
     if (df.columns.dtype.kind == "b") or (  # type: ignore[attr-defined]
         implementation is Implementation.PANDAS and backend_version < (1, 5)
     ):