Merge pull request #82 from anopsy/newmean

mean usage example added

narwhals/expression.py

@@ -274,6 +274,38 @@ def all(self) -> Expr:
         return self.__class__(lambda plx: self._call(plx).all())
 
     def mean(self) -> Expr:
+        """
+        Get mean value.
+
+        Examples:
+            >>> import polars as pl
+            >>> import pandas as pd
+            >>> import narwhals as nw
+            >>> df_pd = pd.DataFrame({'a': [-1, 0, 1], 'b': [2, 4, 6]})
+            >>> df_pl = pl.DataFrame({'a': [-1, 0, 1], 'b': [2, 4, 6]})
+
+            Let's define a dataframe-agnostic function:
+
+            >>> def func(df_any):
+            ...    df = nw.from_native(df_any)
+            ...    df = df.select(nw.col('a', 'b').mean())
+            ...    return nw.to_native(df)
+
+            We can then pass either pandas or Polars to `func`:
+
+            >>> func(df_pd)
+                 a    b
+            0  0.0  4.0
+            >>> func(df_pl)
+            shape: (1, 2)
+            ┌─────┬─────┐
+            │ a   ┆ b   │
+            │ --- ┆ --- │
+            │ f64 ┆ f64 │
+            ╞═════╪═════╡
+            │ 0.0 ┆ 4.0 │
+            └─────┴─────┘
+        """
         return self.__class__(lambda plx: self._call(plx).mean())
 
     def std(self) -> Expr: