Update validator docs

[adriangb]

Goals:

• Update examples for v2
• Emphasize use of Annotated
• Simplify examples to focus on one thing / feature at a time
• Add sections on error handling, ordering of validators and the different modes
• Include better information on the expected signatures and uses for model validators
• Remove some redundant examples/sections

Selected Reviewer: @dmontagu

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	389c464
Status:	✅  Deploy successful!
Preview URL:	https://a62599f5.pydantic-docs2.pages.dev
Branch Preview URL:	https://validators.pydantic-docs2.pages.dev

View logs

[adriangb]

please review

[adriangb]

@tpdorsey apologies just saw you had #6660, I was unaware of it. I think this is a more wholesale rework with valuable changes to the examples and such. Can you bring over the improvements you made there to this PR? Feel free to just push to this branch.

[dmontagu]

I feel like it might make more sense to start with this section than the annotated validators, since 1, this is closer to existing usage, and 2, it doesn't introduce the concept of using Annotated. I feel like it introduces just the concept of a validator function, which then motivates the idea of using Annotated validators as a way to make them reusable by way of a reused type annotation (rather than needing to set up the validator on every model you want to use it with).

I'm fine if you disagree, I just think this topic is quicker to understand and lowers the barrier to understand the annotated ones.

[dmontagu]

Suggested change

	Model validators can be `mode='before'` or `mode='after'` and `mode='wrap'`.
	Model validators can be `mode='before'`, `mode='after'`, or `mode='wrap'`.

It seems a little weird to have both "and" and "or" in the same list here, unless there is something weird going on where mode='after' and mode='wrap' deserve to be considered as a group, separate from mode='before'. (I don't think that's the case, but I just want to make sure I'm not missing some implied nuance here.)

[dmontagu]

LGTM, though I have made various suggestions you can take or leave.