Add typing.Annotated docs

docs/examples/schema_annotated.py

@@ -0,0 +1,10 @@
+try:
+    from typing import Annotated
+except ImportError:
+    from typing_extensions import Annotated
+
+from pydantic import BaseModel, Field
+
+
+class FooBar(BaseModel):
+    count: Annotated[int, Field(gt=-1)] = 0

docs/usage/schema.md

@@ -106,6 +106,21 @@ to `Field()` with the raw schema attribute name:
 ```
 _(This script is complete, it should run "as is")_
 
+### typing.Annotated Fields
+
+Rather than assigning a `Field` value, it can be specified in the type hint with `typing.Annotated`:
+
+```py
+{!.tmp_examples/schema_annotated.py!}
+```
+_(This script is complete, it should run "as is")_
+
+`Field` can only be supplied once per field - an error will be raised it is used in `Annotated` and as the assigned
+value. When used in `Annotated`, `Field` must not contain a default value, instead an assigned default value should be
+used.
+
+For versions of Python prior to 3.9, `typing_extensions.Annotated` can be used.
+
 ## Modifying schema in custom fields
 
 Custom field types can customise the schema generated for them using the `__modify_schema__` class method;

docs/usage/types.md

@@ -69,6 +69,11 @@ with custom properties and validation.
 `typing.Any`
 : allows any value include `None`, thus an `Any` field is optional
 
+`typing.Annotated`
+: allows wrapping another type with arbitrary metadata, as per [PEP-593](https://www.python.org/dev/peps/pep-0593/). The
+  `Annotated` hint may contain a single call to the [`Field` function](schema.md#typingannotated-fields), but otherwise
+  the additional metadata is ignored and the root type is used.
+
 `typing.TypeVar`
 : constrains the values allowed based on `constraints` or `bound`, see [TypeVar](#typevar)