Use default options in constraint docs

[webmozart]

Currently, the basic examples of constraints like GreaterThan don't use the short version for default options:

class Person
{
    /**
     * @Assert\GreaterThan(
     *     value = 18
     * )
     */
    protected $age;
}

The proper (short) way of writing this would be:

class Person
{
    /**
     * @Assert\GreaterThan(18)
     */
    protected $age;
}

I think the "Basic Usage" examples should be fixed in this direction. In addition, a new section "Message Customization" should be added that shows how to write the constraint when customizing the message:

class Person
{
    /**
     * @Assert\GreaterThan(
     *     value = 18,
     *     message = "Restricted to persons older than 18 years."
     * )
     */
    protected $age;
}

The above applies for all configuration styles (annotations, PHP, XML and YAML).

[weaverryan]

Hey Bernhard!

We show the long way because it's easier to migrate from it to using multiple options (or non-default options) when you need them. I think you outline a way that would show the short way and still the longer way. Personally, I'm kind of a +0. The short syntax looks better and saves you some keystrokes, but I'm uncertain as to how that weighs against the cons (less clarity, harder to know how to use a non-default option).

What do others think?

[xabbuh]

I like the idea of simplifying the basic usage examples. I guess that would make life easier for developers. Though we have to find a way to show how to use them with additional options. Wouldn't it be possible to write a generic chapter for that and link to it from each constraint?

[weaverryan]

@xabbuh it would be a bit more work, but I'd rather do what Bernhard is showing - show one example with the default value and then immediately after, another example showing more options.

[webmozart]

Hey Ryan :) Thanks for your thoughtful response!

less clarity

IMO the shorter version is more clear, as long as you don't use other options. GreaterThan(18) can easily be read out loud.

The point to me is that right now many people don't even know that the short version exists. This should be fixed. As you said, if we show the longer version right after the short example, things should be clear to everyone.

[weaverryan]

👍

[alexmart]

I'll give it a try if nobody objects!

[javiereguiluz]

Closing as fixed by #6597.