Documented KeyCompatibilityValidator

As well as slightly improving the documentation of the
KeyCompatibilityValidator class, the internals of the class have been
refactored to improve code readability.  The refactoring does not change
the external behaviour of the class.