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!
Hmm, I don't think so. If you're using 2.5 BC API, then the 2.5 validation API is available to you and you should be using it. I think the fact that you *also* have the ability to use the older API is a detail that they don't need to care about (that's just there so their old code doesn't break).