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 started to make this change, but I think it actually looked worse. The first line is a one-line comment, which you can keep even if you commented out the next block of code.