From 79783ef8c482cd62f8132b45ce1c2fae446b38d5 Mon Sep 17 00:00:00 2001
From: Dan Redding <125183946+dangotbanned@users.noreply.github.com>
Date: Fri, 28 Jun 2024 12:57:01 +0100
Subject: [PATCH] docs: Fix and improve `alt.Optional` doc (#3449)

---
 altair/utils/schemapi.py   | 30 ++++++++++++++++++++++++------
 tools/schemapi/schemapi.py | 30 ++++++++++++++++++++++++------
 2 files changed, 48 insertions(+), 12 deletions(-)

diff --git a/altair/utils/schemapi.py b/altair/utils/schemapi.py
index 822526b2f..8f71247da 100644
--- a/altair/utils/schemapi.py
+++ b/altair/utils/schemapi.py
@@ -746,15 +746,33 @@ def __repr__(self) -> str:
 Undefined = UndefinedType()
 T = TypeVar("T")
 Optional: TypeAlias = Union[T, UndefinedType]
-"""One of the sepcified types, or the `Undefined` singleton.
-
+"""One of ``T`` specified type(s), or the ``Undefined`` singleton.
 
 Examples
 --------
-```py
-MaybeDictOrStr: TypeAlias = Optional[dict[str, Any] | str]
-LongerDictOrStr: TypeAlias = dict[str, Any] | str | UndefinedType
-```
+The parameters ``short``, ``long`` accept the same range of types::
+
+    # ruff: noqa: UP006, UP007
+    from altair import Optional
+
+    def func_1(
+        short: Optional[str | bool | float | dict[str, Any] | SchemaBase] = Undefined,
+        long: Union[
+            str, bool, float, Dict[str, Any], SchemaBase, UndefinedType
+        ] = Undefined,
+    ): ...
+
+This is distinct from `typing.Optional <https://typing.readthedocs.io/en/latest/spec/historical.html#union-and-optional>`__ as ``altair.Optional`` treats ``None`` like any other type::
+
+    # ruff: noqa: UP006, UP007
+    from altair import Optional
+
+    def func_2(
+        short: Optional[str | float | dict[str, Any] | None | SchemaBase] = Undefined,
+        long: Union[
+            str, float, Dict[str, Any], None, SchemaBase, UndefinedType
+        ] = Undefined,
+    ): ...
 """
 
 
diff --git a/tools/schemapi/schemapi.py b/tools/schemapi/schemapi.py
index b9c79414b..b8bbe34c2 100644
--- a/tools/schemapi/schemapi.py
+++ b/tools/schemapi/schemapi.py
@@ -744,15 +744,33 @@ def __repr__(self) -> str:
 Undefined = UndefinedType()
 T = TypeVar("T")
 Optional: TypeAlias = Union[T, UndefinedType]
-"""One of the sepcified types, or the `Undefined` singleton.
-
+"""One of ``T`` specified type(s), or the ``Undefined`` singleton.
 
 Examples
 --------
-```py
-MaybeDictOrStr: TypeAlias = Optional[dict[str, Any] | str]
-LongerDictOrStr: TypeAlias = dict[str, Any] | str | UndefinedType
-```
+The parameters ``short``, ``long`` accept the same range of types::
+
+    # ruff: noqa: UP006, UP007
+    from altair import Optional
+
+    def func_1(
+        short: Optional[str | bool | float | dict[str, Any] | SchemaBase] = Undefined,
+        long: Union[
+            str, bool, float, Dict[str, Any], SchemaBase, UndefinedType
+        ] = Undefined,
+    ): ...
+
+This is distinct from `typing.Optional <https://typing.readthedocs.io/en/latest/spec/historical.html#union-and-optional>`__ as ``altair.Optional`` treats ``None`` like any other type::
+
+    # ruff: noqa: UP006, UP007
+    from altair import Optional
+
+    def func_2(
+        short: Optional[str | float | dict[str, Any] | None | SchemaBase] = Undefined,
+        long: Union[
+            str, float, Dict[str, Any], None, SchemaBase, UndefinedType
+        ] = Undefined,
+    ): ...
 """