From b954edd0749cc0e321d0fd89ab71f1c03071762c Mon Sep 17 00:00:00 2001
From: Nick Crews <nicholas.b.crews@gmail.com>
Date: Thu, 9 Feb 2023 13:36:47 -0900
Subject: [PATCH] docs: improve Expr.substitute() docstring

---
 ibis/expr/types/generic.py | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
index d2a521f8ccb2..59917bb8f6d0 100644
--- a/ibis/expr/types/generic.py
+++ b/ibis/expr/types/generic.py
@@ -289,21 +289,24 @@ def notin(self, values: Value | Sequence[Value]) -> ir.BooleanValue:
 
     def substitute(
         self,
-        value: Value,
+        value: Value | dict,
         replacement: Value | None = None,
         else_: Value | None = None,
     ):
-        """Replace one or more values in a value expression.
+        """Replace values given in `values` with `replacement`.
+
+        This is similar to the pandas `replace` method.
 
         Parameters
         ----------
         value
-            Expression or mapping
+            Expression or dict.
         replacement
-            Expression. If an expression is passed to value, this must be
+            If an expression is passed to value, this must be
             passed.
         else_
-            Expression
+            If an original value does not match `value`, then `else_` is used.
+            The default of `None` means leave the original value unchanged.
 
         Returns
         -------