📝 Add Alternate Form for early adopters

diff --git a/typing_doc.md b/typing_doc.md
index b45f7d6cd1e5e2714b4036d3b021d6df0b60b265..2ab93d8950db6947dee6c0ed1b92da4d0feb1ea7 100644 (file)
--- a/typing_doc.md
+++ b/typing_doc.md
@@ -123,6 +123,35 @@ def utcnow() -> datetime:
     return datetime.utcnow()
 ```
 
+## Alternate Form
+
+To avoid delaying adoption of this proposal until after the `doc()` function has been added to the typing module, type checkers may support an alternative form `__typing_doc__`. This form can be defined locally without any reliance on the `typing` or `typing_extensions` modules. It allows immediate adoption of the specification by library authors. Type checkers that have not yet adopted this specification will retain their current behavior.
+
+To use this alternate form, library authors should include the following declaration within their type stubs or source files.
+
+```Python
+from typing import Any, Callable, Sequence, Type, TypeVar
+
+_T = TypeVar("_T")
+
+
+def __typing_doc__(
+    *,
+    description: str | None = None,
+    deprecated: bool = False,
+    discouraged: bool = False,
+    raises: Sequence[Type[Exception]] | None = None,
+    extra: dict[Any, Any] | None = None,
+) -> Callable[[_T], _T]:
+    # If used within a stub file, the following implementation can be
+    # replaced with "...".
+    return lambda a: a
+```
+
+And then they can use it in the same places they would use `doc()`.
+
+**Note**: this mimics and blatantly copies the pattern from the early versions of the [`dataclass_transform` specification](https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md#alternate-form).
+
 ## Rejected Ideas
 
 A possible alternative would be to support and try to push as a standard one of the existing docstring formats. But that would only solve the standardization.
@@ -135,8 +164,6 @@ Runtime behavior is still not defined. It would probably make sense to have an a
 
 For parameters, it could include the same object in the same `Annotated` type annotations.
 
-It would probably make sense to have a way to support early adopters. The same way the [`dataclass_transform` had an "Alternate Form"](https://github.com/microsoft/pyright/blob/main/specs/dataclass_transforms.md#alternate-form).
-
 ## Copyright
 
 This document is placed in the public domain or under the