📝 Add example of nested Annotated with doc

diff --git a/typing_doc.md b/typing_doc.md
index 3a1e89a888ed6f60da208ccd26b8c565e845741f..2dac29b2301be98af52c8813ef7b9adf80ab333e 100644 (file)
--- a/typing_doc.md
+++ b/typing_doc.md
@@ -127,7 +127,7 @@ def hi(to: Username) -> None: ...
 def hi(to: Annotated[str, doc("The name of a user in the system")]) -> None: ...
 ```
 
-Nevertheless, implementers would not be required to support type aliases outside of the final type annotation to be conformant with this specification, as it could require more complex derefrenecing logic. If they do, they could state they also support the optional type aliases.
+Nevertheless, implementers would not be required to support type aliases outside of the final type annotation to be conformant with this specification, as it could require more complex derefrenecing logic.
 
 #### Annotating Type Parameters
 
@@ -155,6 +155,27 @@ In particular, the documentation would not refer to a single string passed as a
 
 There are currently no practical use cases for documenting unions, so implementers are not required to support this scenario to be considered conformant, but it's included for completeness.
 
+#### Multiple `Annotated`
+
+Continuing with the same idea above, if `Annotated` was used multiple times in the same parameter, `doc()` would refer to the type it is annotating.
+
+So, in an example like:
+
+```Python
+def hi(to: Annotated[
+        Annotated[str, doc("A user name")] | Annotated[list, doc("A list of user names")],
+        doc("Who to say hi to")
+    ]) -> None: ...
+```
+
+The documentation for the whole parameter `to` would be considered to be "`Who to say hi to`".
+
+The documentation for the case where that parameter `to` is specifically a `str` would be considered to be "`A user name`".
+
+The documentation for the case where that parameter `to` is specifically a `list` would be considered to be "`A list of user names`".
+
+Implementers would only be required to support the top level use case, where the documentation for `to` is considered to be "`Who to say hi to`". They could optionally support having conditional documentation for when the type of the parameter passed is of one type or another, but they are not required to do so.
+
 #### Duplications
 
 If `doc()` is used multiple times in a single `Annotated`, it would be considered invalid usage from the developer, for example: