docs: document args and returns in dataframe (#1594)

narwhals/dataframe.py

@@ -536,6 +536,9 @@ def to_native(self) -> DataFrameT:
     def to_pandas(self) -> pd.DataFrame:
         """Convert this DataFrame to a pandas DataFrame.
 
+        Returns:
+            A pandas DataFrame.
+
         Examples:
             Construct pandas, Polars (eager) and PyArrow DataFrames:
 
@@ -581,8 +584,15 @@ def to_pandas(self) -> pd.DataFrame:
     def write_csv(self, file: str | Path | BytesIO | None = None) -> Any:
         r"""Write dataframe to comma-separated values (CSV) file.
 
+        Arguments:
+            file: String, path object or file-like object to which the dataframe will be
+                written. If None, the resulting csv format is returned as a string.
+
+        Returns:
+            String or None.
+
         Examples:
-            Construct pandas and Polars DataFrames:
+            Construct pandas, Polars (eager) and PyArrow DataFrames:
 
             >>> import pandas as pd
             >>> import polars as pl
@@ -613,9 +623,16 @@ def write_csv(self, file: str | Path | BytesIO | None = None) -> Any:
         """
         return self._compliant_frame.write_csv(file)
 
-    def write_parquet(self, file: str | Path | BytesIO) -> Any:
+    def write_parquet(self, file: str | Path | BytesIO) -> None:
         """Write dataframe to parquet file.
 
+        Arguments:
+            file: String, path object or file-like object to which the dataframe will be
+                written.
+
+        Returns:
+            None.
+
         Examples:
             Construct pandas, Polars and PyArrow DataFrames:
 
@@ -645,6 +662,9 @@ def write_parquet(self, file: str | Path | BytesIO) -> Any:
     def to_numpy(self) -> np.ndarray:
         """Convert this DataFrame to a NumPy ndarray.
 
+        Returns:
+            A NumPy ndarray array.
+
         Examples:
             Construct pandas and polars DataFrames:
 
@@ -687,6 +707,9 @@ def to_numpy(self) -> np.ndarray:
     def shape(self) -> tuple[int, int]:
         """Get the shape of the DataFrame.
 
+        Returns:
+            The shape of the dataframe as a tuple.
+
         Examples:
             Construct pandas and polars DataFrames:
 
@@ -721,6 +744,12 @@ def shape(self) -> tuple[int, int]:
     def get_column(self, name: str) -> Series[Any]:
         """Get a single column by name.
 
+        Arguments:
+            name: The column name as a string.
+
+        Returns:
+            A Narwhals Series, backed by a native series.
+
         Notes:
             Although `name` is typed as `str`, pandas does allow non-string column
             names, and they will work when passed to this function if the
@@ -883,6 +912,9 @@ def __getitem__(
                     _inclusive_ and returns a `DataFrame`. For example, if the columns are
                     `'a', 'd', 'c', 'b'`, then that would extract columns `'a'`, `'d'`, and `'c'`.
 
+        Returns:
+            A Narwhals Series, backed by a native series.
+
         Notes:
             - Integers are always interpreted as positions
             - Strings are always interpreted as column names.