From 798848d4802a314ac05f8b20d16635afb8a45bc3 Mon Sep 17 00:00:00 2001
From: Stijn de Gooijer <stijn@degooijer.io>
Date: Thu, 9 Nov 2023 12:11:09 +0100
Subject: [PATCH] Update docs

---
 crates/polars-plan/src/dsl/mod.rs |  2 +-
 py-polars/polars/expr/expr.py     | 31 +++++++++++++++----------------
 py-polars/polars/series/series.py | 22 +++++++++++-----------
 3 files changed, 27 insertions(+), 28 deletions(-)

diff --git a/crates/polars-plan/src/dsl/mod.rs b/crates/polars-plan/src/dsl/mod.rs
index b707b5cabc83..d5f761f19e3b 100644
--- a/crates/polars-plan/src/dsl/mod.rs
+++ b/crates/polars-plan/src/dsl/mod.rs
@@ -816,7 +816,7 @@ impl Expr {
         self.map_private(FunctionExpr::Round { decimals })
     }
 
-    /// Round underlying floating point array to given significant figures.
+    /// Round to a number of significant figures.
     #[cfg(feature = "round_series")]
     pub fn round_sig_figs(self, digits: i32) -> Self {
         self.map_private(FunctionExpr::RoundSF { digits })
diff --git a/py-polars/polars/expr/expr.py b/py-polars/polars/expr/expr.py
index 7fab082faa61..5a4cb63bef93 100644
--- a/py-polars/polars/expr/expr.py
+++ b/py-polars/polars/expr/expr.py
@@ -1788,28 +1788,27 @@ def round(self, decimals: int = 0) -> Self:
 
     def round_sig_figs(self, digits: int) -> Self:
         """
-        Round underlying floating point data by `decimals` digits.
+        Round to a number of significant figures.
 
         Parameters
         ----------
-        significant_figures
-            Number of significant figures to round by.
+        digits
+            Number of significant figures to round to.
 
         Examples
         --------
-        >>> df = pl.DataFrame({"a": [0.33, 0.52, 1.02, 1.17]})
-        >>> df.select(pl.col("a").round_sig_figs(2))
-        shape: (4, 1)
-        ┌──────┐
-        │ a    │
-        │ ---  │
-        │ f64  │
-        ╞══════╡
-        │ 0.33 │
-        │ 0.52 │
-        │ 1.0  │
-        │ 1.2  │
-        └──────┘
+        >>> df = pl.DataFrame({"a": [0.01234, 3.333, 1234.0]})
+        >>> df.with_columns(pl.col("a").round_sig_figs(2).alias("round_sig_figs"))
+        shape: (3, 2)
+        ┌─────────┬────────────────┐
+        │ a       ┆ round_sig_figs │
+        │ ---     ┆ ---            │
+        │ f64     ┆ f64            │
+        ╞═════════╪════════════════╡
+        │ 0.01234 ┆ 0.012          │
+        │ 3.333   ┆ 3.3            │
+        │ 1234.0  ┆ 1200.0         │
+        └─────────┴────────────────┘
 
         """
         return self._from_pyexpr(self._pyexpr.round_sig_figs(digits))
diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py
index ccc053851540..272a2276a5ff 100644
--- a/py-polars/polars/series/series.py
+++ b/py-polars/polars/series/series.py
@@ -4698,25 +4698,25 @@ def round(self, decimals: int = 0) -> Series:
 
     def round_sig_figs(self, digits: int) -> Series:
         """
-        Round underlying floating point data by `significant` figures.
+        Round to a number of significant figures.
+
+        Parameters
+        ----------
+        digits
+            Number of significant figures to round to.
 
         Examples
         --------
-        >>> s = pl.Series("a", [0.12345, 2.56789, 39.01234])
+        >>> s = pl.Series([0.01234, 3.333, 1234.0])
         >>> s.round_sig_figs(2)
         shape: (3,)
-        Series: 'a' [f64]
+        Series: '' [f64]
         [
-                0.12
-                2.6
-                39.0
+                0.012
+                3.3
+                1200.0
         ]
 
-        Parameters
-        ----------
-        digits
-            number of significant figures to round by.
-
         """
 
     def dot(self, other: Series | ArrayLike) -> float | None: