Enhance docs

Author: yevhenii-nadtochii

java-api/src/main/kotlin/io/spine/validation/api/MessageValidator.kt

@@ -32,13 +32,14 @@ import io.spine.annotation.SPI
 /**
  * A validator for an external Protobuf message of type [M].
  *
- * This interface allows adding validation logic to messages, for which there is
- * no control over the generated code.
+ * This interface enforces validation rules for `Message`s whose Java/Kotlin classes
+ * are already generated by third parties, in case they are used in the Protobuf
+ * codebase to which the Validation library is applied.
  *
  * ## Problem
  *
  * Java/Kotlin libraries that use Protobuf messages often distribute both the `.proto`
- * definitions and the compiled class files (.class) for these messages.
+ * definitions and the compiled class files (`.class`) for these messages.
  * As these classes are pre-generated, consumers cannot modify their underlying
  * `.proto` files to define validation constraints and the Validation library
  * cannot use code generation to enforce the constraints.
@@ -103,12 +104,20 @@ import io.spine.annotation.SPI
  * and `EarphonesValidator` classes are declared, then the generated code of `WorkingSetup`
  * will apple the validator to each instance passed to the `WorkingSetup.earphones` field.
  *
+ * Please note that the following use cases are NOT supported and will lead to an error:
+ *
+ * 1) Declaring a validator for a local message is prohibited. Only external messages are
+ *    allowed to have a validator. Use built-in or custom validation options to declare
+ *    constraints for local messages.
+ * 2) Declaring multiple validators for the same message type is prohibited. The library
+ *    scans the module’s classpath to discover validators, and expects exactly one validator
+ *    per message type.
+ *
  * ## Implementation
  *
- * The message validator does not have restrictions upon how exactly the message
- * must be validated. It can validate a particular field, several fields,
- * the whole message instance (for example, checking the field relations),
- * and perform a deep validation.
+ * The interface offers flexible validation strategies. Implementations can choose to
+ * validate a particular field, several fields, the whole message instance (for example,
+ * checking the field relations), and perform a deep validation.
  *
  * It is a responsibility of the validator to provide the correct instances
  * of [DetectedViolation]. Before reporting to the user, the library converts
@@ -119,14 +128,6 @@ import io.spine.annotation.SPI
  * is created. Every implementation of [MessageValidator] must have a public,
  * no-args constructor.
  *
- * An implementation of [MessageValidator] will be rejected by the library
- * in the following cases:
- *
- * 1) It is used to validate a local message. Only external messages are allowed
- *    to have a validator.
- * 2) There already exists a validator for the specified message type. Having several
- *    validators for the same message type is prohibited.
- *
  * @param M the type of Protobuf [Message] being validated.
  */
 @SPI