/*
 * Copyright 2019, TeamDev. All rights reserved.
 *
 * Redistribution and use in source and/or binary forms, with or without
 * modification, must retain the above copyright notice and the following
 * disclaimer.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package io.spine.tools.validate.field;

import com.squareup.javapoet.CodeBlock;
import io.spine.tools.validate.AccumulateViolations;
import io.spine.validate.ConstraintViolation;

/**
 * A message validation constraint.
 *
 * <p>A {@code Constraint} may represent one or several validation  applied to a message. In
 * general, a notion of being followed or broken is present for a rule.
 */
public interface Constraint {

    /**
     * Compiles this rule into the Java validation code.
     *
     * <p>If the rule is broken, one or more {@link ConstraintViolation}s are passed to
     * the {@link AccumulateViolations}.
     *
     * @param onViolation
     *         a function which accept a {@link ConstraintViolation} and yields it to where the
     *         violations are accumulated for the validated message
     * @return a function which accepts the field value and returns the validation code
     */
    default CodeBlock compile(AccumulateViolations onViolation) {
        return compile(onViolation, CodeBlock.of(""));
    }

    /**
     * Compiles this constraint into the Java validation code.
     *
     * <p>If the constraint is violated, one or more {@link ConstraintViolation}s are passed to
     * the {@link AccumulateViolations}. If the message follows the rule, no violations are produced
     * and the {@code orElse} code block is executed.
     *
     * @param onViolation
     *         a function which accept a {@link ConstraintViolation} and yields it to where the
     *         violations are accumulated for the validated message
     * @param orElse
     *         if the rule does not add a violation, this code will be invoked
     * @return a function which accepts the field value and returns the validation code
     */
    CodeBlock compile(AccumulateViolations onViolation, CodeBlock orElse);
}

@@ -1199,205 +1199,734 @@
 * A 
-message valid
+validation rule applied to a message type.%0A *%0A * %3Cp%3EMay represent a limit
 ation 
-c
 on
-straint.%0A *%0A * %3Cp%3EA %7B@code Constraint%7D may represent one or several validation  applied to a message. In%0A * general, a notion of being followed or broken is present for a rule
+ acceptable values of a field, a rule describing a field%0A * relationship, etc.%0A *%0A * %3Cp%3EExamples:%0A * %3Cul%3E%0A *     %3Cli%3EField %7B@code spec%7D in %7B@code spine.net.Url%7D must be set.%0A *     %3Cli%3EString field %7B@code phone_number%7D in %7B@code com.acme.ContactInfo%7D must match regular%0A *         expression %7B@code %22%5C+?%5Cd+%22%7D.%0A *     %3Cli%3EMessage of type %7B@code spine.people.PersonName%7D must have at least %7B@code given_name%7D or%0A *         both %7B@code honorific_prefix%7D and %7B@code family_name%7D fields set.%0A * %3C/ul%3E%0A *%0A * %3Cp%3EIn Protobuf, validation constraints are expressed with options.%0A * See %7B@code spine/options.proto%7D for the definitions of validation options
 .%0A *

Rephrase doc for `Constraint`