Improved Documentation

[sydney-runkle]

It'd be great to improve documentation, especially for the public types listed here.

I think this will pair well with the architecture docs improvement in pydantic, see this issue.

[AdolfoVillalobos]

Hi @sydney-runkle

I've been delving into rust for a while and would love to contribute a bit to this project.

Before submitting a PR, I would love to clarify that my understanding of these errors is correct. Let's consider PydanticCustomError.

As I understand it, PydanticCustomError is a custom error type that allows users to define their error types and messages during validation. It's part of the ValidationError system and can be used to create domain-specific error messages.

A simple example would be raising PydanticCustomError inside a custom validator:

from pydantic_core import SchemaValidator, ValidationError, PydanticCustomError

def custom_validator(value):
    if value < 0:
        raise PydanticCustomError(
            'negative_number',
            'Number must be positive, got {number}',
            {'number': value}
        )
    return value

schema = {
    'type': 'function-plain',
    'function': custom_validator,
    'schema': {'type': 'int'}
}

validator = SchemaValidator(schema)

try:
    validator.validate_python(-5)
except ValidationError as e:
    print(e)

If all this interpretation is correct, a good start for documenting the error might be:

@final
class PydanticCustomError(ValueError):
    """
    `PydanticCustomError` is a custom exception class that can be used to create specific error types
    with custom messages during validation in pydantic-core.
    """

    def __new__(
        cls, error_type: LiteralString, message_template: LiteralString, context: dict[str, Any] | None = None
    ) -> Self:
        """
        Create a new PydanticCustomError instance.

        Arguments:
            error_type: A string identifier for the type of error.
            message_template: A template string for the error message, which can include placeholders.
            context: An optional dictionary containing context information for the error.
        """
       # rest of the class definition...

I would replicate the documentation style of the ValidationError.

---

To summarize: Is this understanding correct? Thanks!

[AdolfoVillalobos]

@sydney-runkle nvm, I just realized PR #1420 addresses this issue

[sydney-runkle]

@AdolfoVillalobos, yes - your understanding here is correct! Indeed, we already have a PR up to address this issue, but would certainly welcome your help on others!! :)