Repository: pydantic/pydantic

Issue:
Improve cross links between `Usage` and `API Documentation` sections in the docs



Discussion:

Resolving patch:
diff --git a/pydantic/functional_validators.py b/pydantic/functional_validators.py
--- a/pydantic/functional_validators.py
+++ b/pydantic/functional_validators.py
@@ -288,6 +288,42 @@ def field_validator(
 
     Decorate methods on the class indicating that they should be used to validate fields.
 
+    Example usage:
+    ```py
+    from typing import Any
+
+    from pydantic import (
+        BaseModel,
+        ValidationError,
+        field_validator,
+    )
+
+    class Model(BaseModel):
+        a: str
+
+        @field_validator('a')
+        @classmethod
+        def ensure_foobar(cls, v: Any):
+            if 'foobar' not in v:
+                raise ValueError('"foobar" not found in a')
+            return v
+
+    print(repr(Model(a='this is foobar good')))
+    #> Model(a='this is foobar good')
+
+    try:
+        Model(a='snap')
+    except ValidationError as exc_info:
+        print(exc_info)
+        '''
+        1 validation error for Model
+        a
+          Value error, "foobar" not found in a [type=value_error, input_value='snap', input_type=str]
+        '''
+    ```
+
+    For more in depth examples, see [Field Validators](../concepts/validators.md#field-validators).
+
     Args:
         __field: The first field the `field_validator` should be called on; this is separate
             from `fields` to ensure an error is raised if you don't pass at least one.
@@ -461,6 +497,39 @@ def model_validator(
 
     Decorate model methods for validation purposes.
 
+    Example usage:
+    ```py
+    from typing import Optional
+
+    from pydantic import BaseModel, ValidationError, model_validator
+
+    class Square(BaseModel):
+    width: float
+    height: float
+
+    @model_validator(mode='after')
+    def verify_square(self) -> 'Rectangle':
+        if self.width != self.height:
+            raise ValueError('width and height do not match')
+        return self
+
+    s = Square(width=1, height=1)
+    print(repr(s))
+    #> Square(width=1.0, height=1.0)
+
+    try:
+        Square(width=1, height=2)
+    except ValidationError as e:
+        print(e)
+        '''
+        1 validation error for Square
+        __root__
+          width and height do not match (type=value_error)
+        '''
+    ```
+
+    For more in depth examples, see [Model Validators](../concepts/validators.md#model-validators).
+
     Args:
         mode: A required string literal that specifies the validation mode.
             It can be one of the following: 'wrap', 'before', or 'after'.
diff --git a/pydantic/json_schema.py b/pydantic/json_schema.py
--- a/pydantic/json_schema.py
+++ b/pydantic/json_schema.py
@@ -1,4 +1,6 @@
 """
+Usage docs: https://docs.pydantic.dev/2.5/concepts/json_schema/
+
 The `json_schema` module contains classes and functions to allow the way [JSON Schema](https://json-schema.org/)
 is generated to be customized.
 
@@ -220,7 +222,9 @@ def remap_json_schema(self, schema: Any) -> Any:
 
 
 class GenerateJsonSchema:
-    """A class for generating JSON schemas.
+    """Usage docs: https://docs.pydantic.dev/2.5/concepts/json_schema/#customizing-the-json-schema-generation-process
+
+    A class for generating JSON schemas.
 
     This class generates JSON schemas based on configured parameters. The default schema dialect
     is [https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema).
diff --git a/pydantic/types.py b/pydantic/types.py
--- a/pydantic/types.py
+++ b/pydantic/types.py
@@ -109,7 +109,9 @@
 
 @_dataclasses.dataclass
 class Strict(_fields.PydanticMetadata, BaseMetadata):
-    """A field metadata class to indicate that a field should be validated in strict mode.
+    """Usage docs: https://docs.pydantic.dev/2.5/concepts/strict_mode/#strict-mode-with-annotated-strict
+
+    A field metadata class to indicate that a field should be validated in strict mode.
 
     Attributes:
         strict: Whether to validate the field in strict mode.
@@ -667,7 +669,9 @@ def conbytes(
 
 @_dataclasses.dataclass(frozen=True)
 class StringConstraints(annotated_types.GroupedMetadata):
-    """Apply constraints to `str` types.
+    """Usage docs: https://docs.pydantic.dev/2.5/concepts/fields/#string-constraints
+
+    Apply constraints to `str` types.
 
     Attributes:
         strip_whitespace: Whether to strip whitespace from the string.
@@ -2400,7 +2404,9 @@ class Model(BaseModel):
 
 @_dataclasses.dataclass(**_internal_dataclass.slots_true)
 class GetPydanticSchema:
-    """A convenience class for creating an annotation that provides pydantic custom type hooks.
+    """Usage docs: https://docs.pydantic.dev/2.5/concepts/types/#using-getpydanticschema-to-reduce-boilerplate
+
+    A convenience class for creating an annotation that provides pydantic custom type hooks.
 
     This class is intended to eliminate the need to create a custom "marker" which defines the
      `__get_pydantic_core_schema__` and `__get_pydantic_json_schema__` custom hook methods.
@@ -2513,12 +2519,13 @@ class ThanksgivingDinner(BaseModel):
     ```
 
     !!! note
-        You must specify a `Tag` for every case in a `Union` that is associated with a
+        You must specify a `Tag` for every case in a `Tag` that is associated with a
         callable `Discriminator`. Failing to do so will result in a `PydanticUserError` with code
         [`callable-discriminator-no-tag`](../errors/usage_errors.md#callable-discriminator-no-tag).
 
-    See the [Discriminated Unions](../concepts/unions.md#discriminated-unions)
-    docs for more details on how to use `Tag`s.
+    See the [Discriminated Unions] concepts docs for more details on how to use `Tag`s.
+
+    [Discriminated Unions]: ../concepts/unions.md#discriminated-unions
     """
 
     tag: str
@@ -2533,7 +2540,7 @@ def __get_pydantic_core_schema__(self, source_type: Any, handler: GetCoreSchemaH
 
 @_dataclasses.dataclass(**_internal_dataclass.slots_true, frozen=True)
 class Discriminator:
-    """[Usage docs](../concepts/unions.md#discriminated-unions)
+    """Usage docs: https://docs.pydantic.dev/2.5/concepts/unions/#discriminated-unions-with-callable-discriminator
 
     Provides a way to use a custom callable as the way to extract the value of a union discriminator.
 
@@ -2600,8 +2607,9 @@ class ThanksgivingDinner(BaseModel):
     '''
     ```
 
-    See the [Discriminated Unions](../concepts/unions.md#discriminated-unions)
-    docs for more details on how to use `Discriminator`s.
+    See the [Discriminated Unions] concepts docs for more details on how to use `Discriminator`s.
+
+    [Discriminated Unions]: ../concepts/unions.md#discriminated-unions
     """
 
     discriminator: str | Callable[[Any], Hashable]


Test patch: