2.5 Validation API changes

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | 2.5
| Fixed tickets | #4094

Hi guys!

This takes the work in #4056, #4105 and #4161 and extends it based on some feedback. Basically, the whole validation stuff is quite difficult, because:

A) We want to show the non-deprecated methods so people use the new stuff
B) We don't want to confuse users on the 2.4 API (even though this number of users should be very small, as it would require you to have started a project in the past and be using 5.3.9 and lower https://github.com/symfony/symfony-docs/pull/4105#issuecomment-51594463)

This solution is to show the new way, but always show the old way in comments. This would check of A and B in #4094.

Thanks!
I prefer to either use either single line or multi line comments, not both:

````php
// If you're using the old 2.4 validation API
// $this->context->addValidation(
//     ...
// );
````

````php
/* If you're using the old 2.4 validation API
$this->context->addViolation(
    ...
);
*/
````