docs: Enable darglint for dataframe and series modules (#2931)

* docs: Enable darglint for dataframe and series modules

* docstring to comment

Author: FBruzzesi

.pre-commit-config.yaml

@@ -26,18 +26,15 @@ repos:
     hooks:
     -   id: flake8
         additional_dependencies: [darglint==1.8.1, Flake8-pyproject]
-        entry: flake8 --select DAR --ignore DAR101,DAR402,DAR401
+        entry: flake8 --select DAR --ignore DAR101,DAR401,DAR402
         exclude: |
             (?x)^(
                 tests/.*|
                 # TODO: gradually enable
-                narwhals/series\.py|
-                # TODO: gradually enable
-                narwhals/dataframe\.py|
-                # TODO: gradually enable
                 narwhals/dependencies\.py|
-                # private, so less urgent to document too well
+                # Private, so less urgent to document too well
                 narwhals/_.*|
+                # Internal use only, less urgent
                 ^utils/.*|
                 # Soft-deprecated, so less crucial to document so carefully
                 narwhals/stable/v1/.*

narwhals/dataframe.py

@@ -112,7 +112,8 @@ def _with_compliant(self, df: Any) -> Self:
     def _flatten_and_extract(
         self, *exprs: IntoExpr | Iterable[IntoExpr], **named_exprs: IntoExpr
     ) -> tuple[list[CompliantExprAny], list[ExprKind]]:
-        """Process `args` and `kwargs`, extracting underlying objects as we go, interpreting strings as column names."""
+        # Process `args` and `kwargs`, extracting underlying objects as we go.
+        # NOTE: Strings are interpreted as column names.
         out_exprs = []
         out_kinds = []
         for expr in flatten(exprs):
@@ -700,6 +701,9 @@ def __arrow_c_stream__(self, requested_schema: object | None = None) -> object:
 
         See [PyCapsule Interface](https://arrow.apache.org/docs/dev/format/CDataInterface/PyCapsuleInterface.html)
         for more.
+
+        Returns:
+            A PyCapsule containing a C ArrowArrayStream representation of the object.
         """
         native_frame = self._compliant_frame._native_frame
         if supports_arrow_c_stream(native_frame):
@@ -900,9 +904,6 @@ def write_parquet(self, file: str | Path | BytesIO) -> None:
             file: String, path object or file-like object to which the dataframe will be
                 written.
 
-        Returns:
-            None.
-
         Examples:
             >>> import pyarrow as pa
             >>> import narwhals as nw
@@ -1459,7 +1460,7 @@ def with_columns(
                             The columns will be renamed to the keyword used.
 
         Returns:
-            DataFrame: A new DataFrame with the columns added.
+            New DataFrame with the columns added.
 
         Note:
             Creating a new DataFrame using this method does not create a new copy of
@@ -2744,7 +2745,7 @@ def with_columns(
                             The columns will be renamed to the keyword used.
 
         Returns:
-            LazyFrame: A new LazyFrame with the columns added.
+            New LazyFrame with the columns added.
 
         Note:
             Creating a new LazyFrame using this method does not create a new copy of
@@ -3044,9 +3045,6 @@ def sink_parquet(self, file: str | Path | BytesIO) -> None:
             file: String, path object or file-like object to which the dataframe will be
                 written.
 
-        Returns:
-            None.
-
         Examples:
             >>> import polars as pl
             >>> import narwhals as nw

narwhals/series.py

@@ -268,6 +268,9 @@ def __arrow_c_stream__(self, requested_schema: object | None = None) -> object:
 
         See [PyCapsule Interface](https://arrow.apache.org/docs/dev/format/CDataInterface/PyCapsuleInterface.html)
         for more.
+
+        Returns:
+            A PyCapsule containing a C ArrowArrayStream representation of the object.
         """
         native_series = self._compliant_series.native
         if supports_arrow_c_stream(native_series):
@@ -773,6 +776,9 @@ def max(self) -> Any:
     def arg_min(self) -> int:
         """Returns the index of the minimum value.
 
+        Returns:
+            The index of the min value in the Series.
+
         Examples:
             >>> import pyarrow as pa
             >>> import narwhals as nw
@@ -786,6 +792,9 @@ def arg_min(self) -> int:
     def arg_max(self) -> int:
         """Returns the index of the maximum value.
 
+        Returns:
+            The index of the max value in the Series.
+
         Examples:
             >>> import polars as pl
             >>> import narwhals as nw
@@ -819,7 +828,7 @@ def std(self, *, ddof: int = 1) -> float:
 
         Arguments:
             ddof: "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof,
-                     where N represents the number of elements.
+                    where N represents the number of elements.
 
         Returns:
             The standard deviation of all elements in the Series.
@@ -839,7 +848,10 @@ def var(self, *, ddof: int = 1) -> float:
 
         Arguments:
             ddof: "Delta Degrees of Freedom": the divisor used in the calculation is N - ddof,
-                     where N represents the number of elements.
+                    where N represents the number of elements.
+
+        Returns:
+            The variance of all elements in the Series.
 
         Examples:
             >>> import pyarrow as pa