Clarify "always" usage in validator migration guide and field validator doc

[benbenbang]

Initial Checks

• I confirm that I'm using Pydantic V2

Description

Hello team,

First of all, thanks for the great work! And sorry if this request is not qualified as a "bug"

Context:
I am currently migrating from the v1 API to v2 and encountered a small hurdle related to the usage of always in the validator section.

While going through the pages, I found it slightly convoluted to find the doc with this particular migration or at least identify the closest alternative in the v2 API. After some exploration, I stumbled upon the validate_default argument in the Field API, which seems to offer the closest behavior to what I need.

However, it took some effort to discover this option. I believe it would greatly benefit the community if we could clarify this usage in the migration guide and the field validator documentation. To contribute, I will be happy to create a quick PR to update the doc.

Thanks again.

Example Code

The following are the confusing parts:

• In the migration guide, it says:

If you use the always=True keyword argument to a validator function, note that standard validators for the annotated type will also be applied even to defaults, not just the custom validators. For example, despite the fact that the validator below will never error, the following code raises a ValidationError:

but it never mentioned how to migrate to v2

• And in the Field API doc, it states:

Run validation that isn't only checking the existence of defaults. True by default.

The default value doesn't seem to be True since the behaviors of putting True or leaving it as "default" differ.

Python, Pydantic & OS Version

pydantic version: 2.0.3
pydantic-core version: 2.3.0 release build profile
install path: ./.venv/lib/python3.10/site-packages/pydantic
python version: 3.10.11 (main, Feb 18 2023, 20:53:20) [Clang 14.0.0 (clang-1400.0.29.202)]
platform: macOS-13.4.1-arm64-arm-64bit
optional deps. installed: ['typing-extensions']

Selected Assignee: @samuelcolvin

[hramezani]

Thanks @benbenbang for reporting this.

Happy to review a PR that improv the doc

[benbenbang]

Hello @hramezani. I opened a PR and made several updates.