I don't understand this PR. Can you expand a bit on the motivation, and give some examples maybe?

Sure, the motivation is to be explicit about the fact that the typecast processors, such as bool:, may, in fact, return a non-bool value. I have come across this when I wanted to pass an env-variable into a service which has a typed bool constructor argument.

The logic I wanted to implement was

If OPTIONAL_ENV_VAR is defined and "trueish", pass true. Otherwise pass false.

The services.yaml file would have the following:

    \EnvironmentService:
        arguments:
            $boolFlag: '%env(bool:default::OPTIONAL_ENV_VAR)%'

However, I found out that the bool: processor would return null when OPTIONAL_ENV_VAR was not defined. That would crash PHP when the constructor of the service was invoked. I had to do the following and accept ?bool.

final class EnvironmentService
{
    public readonly bool $boolFlag;

    public function __construct(
        ?bool $boolFlag,
    ) {
        $this->boolFlag = $boolFlag ?? false;
    }
}

I think this behavior of Symfony is perfectly fine, but it's not immediately clear from the documentation that all the processors can return nullable types. When I read the doc for bool:, I expected it to always return a boolean value, like PHP's (bool) $x typecast does (which converts null to false). This MR should make that clearer.

Actually, that happens because of the default processor in the chain.
I don't think we should merge this into the doc.
Instead can you please consider filling a bug report?

Let's close this then as a doc issue ... and @melkamar, if you can, please open an issue in the Symfony code repository to discuss about this --> https://github.com/symfony/symfony/issues/new/choose

Thanks!