📝 📝 Add raises parameter as suggested in an informal chat with @Kludex

typing_doc.md

@@ -40,6 +40,7 @@ This `doc()` function would receive several parameters for metadata and document
     * This could probably contain markup, like Markdown or reST. As that could be highly debated, that decision is left for a future proposal, to focus here on the main functionality.
 * `deprecated: bool`: this would mark a parameter, class, function, or method as deprecated. Editors could display it with a strike-through or other appropriate formatting.
 * `discouraged: bool`: this would mark a parameter, class, function, or method as discouraged. Editors could display them similar to `deprecated`. The reason why having a `discouraged` apart from `deprecated` is that there are cases where something is not gonna be removed for backward compatibility, but it shouldn't be used in new code. An example of this is `datetime.utcnow()`.
+* `raises: Sequence[Type[Exception]]`: in a class, function, or method, this indicates the types of exceptions that could be raised by calling it. Editors and tooling could show a warning (e.g. a colored underline) if the call is not wrapped in a `try` block or the parent caller doesn't include the same exceptions in its `raises` parameter.
 * `extra: dict`: a dictionary containing any additional metadata that could be useful for developers or library authors.
     * An `extra` parameter instead of `**kwargs` is proposed to allow adding future standard parameters.
 * `**kwargs: Any`: allows arbitrary additional keyword args. This gives type checkers the freedom to support experimental parameters without needing to wait for changes in `typing.py`. Type checkers should report errors for any unrecognized parameters. This follows the same pattern designed in [PEP 681 – Data Class Transforms](https://peps.python.org/pep-0681/).
@@ -73,7 +74,7 @@ An example documenting a function could look like this:
 ```python
 from typing import Annotated, doc
 
-@doc(description="Create a new user in the system")
+@doc(description="Create a new user in the system", raises=[InvalidUserError, UserExistsError])
 def create_user(
     lastname: Annotated[
         str, doc(description="The **last name** of the newly created user")