Updated the documentation for validator

The existing description of custom validators is pretty confusing, in particular the examples, so I re-wrote this section based on my experiences.