Enhance documentation at Restrict

api/src/main/java/jakarta/data/BasicRestriction.java

@@ -17,13 +17,76 @@
  */
 package jakarta.data;
 
+/**
+ * Represents a specific condition or restriction applied to a query.
+ * A {@code BasicRestriction} encapsulates a comparison operation ({@link Operator}),
+ * a field name, and a value. It is used to define precise query filters or criteria
+ * that target specific fields and values within a dataset. Restrictions can also
+ * be negated to dynamically adjust query logic.
+ * Example usage:
+ * <pre>{@code
+ * BasicRestriction<Person> restriction = ...
+ * String field = restriction.field(); // e.g., "name"
+ * Operator operator = restriction.comparison(); // e.g., EQUAL
+ * Object value = restriction.value(); // e.g., "John"
+ * }</pre>
+ *
+ * @param <T> the type of the value being restricted
+ */
 public interface BasicRestriction<T> extends Restriction<T> {
+
+    /**
+     * Returns the comparison operator associated with this restriction.
+     * <p>
+     * The operator defines the logical relationship between the field and the value,
+     * such as equality, greater than, less than, or inclusion in a set.
+     * For example:
+     * <ul>
+     *   <li>{@link Operator#EQUAL} for equality (e.g., {@code field = value})</li>
+     *   <li>{@link Operator#IN} for inclusion in a set (e.g., {@code field IN (values)})</li>
+     * </ul>
+     * </p>
+     *
+     * @return the {@link Operator} for this restriction
+     */
     Operator comparison();
 
+    /**
+     * Returns the name of the entity field targeted by this restriction.
+     * The field name represents the specific attribute of the entity
+     * that this restriction applies to. For example, in a query filtering
+     * {@code Person} entities by name, the field might be "name."
+     *
+     * @return the name of the field
+     */
     String field();
 
+    /**
+     * Returns the value associated with this restriction.
+     * The value is compared against the field using the specified {@link #comparison()} operator.
+     * For example, in a restriction like {@code name = "John"}, the value is "John."
+     *
+     * @return the value being restricted
+     */
+    Object value();
+
+    /**
+     * Returns a negated version of this restriction.
+     * Negating a restriction inverts its logic. For example:
+     * <ul>
+     *   <li>A restriction with {@link Operator#EQUAL} becomes {@link Operator#NOT_EQUAL}</li>
+     *   <li>A restriction with {@link Operator#IN} becomes {@link Operator#NOT_IN}</li>
+     * </ul>
+     * The negated restriction retains the same field and value but uses the negated operator.
+     * Example:
+     * <pre>{@code
+     * BasicRestriction<Person> restriction = ... // age > 30
+     * BasicRestriction<Person> negated = restriction.negate(); // age <= 30
+     * }</pre>
+     *
+     * @return a negated version of this restriction
+     * @see Operator#negate()
+     */
     @Override
     BasicRestriction<T> negate();
-
-    Object value();
 }

api/src/main/java/jakarta/data/CompositeRestriction.java

@@ -19,18 +19,83 @@
 
 import java.util.List;
 
+/**
+ * Represents a composite restriction that combines multiple individual restrictions on an entity.
+ * A {@code CompositeRestriction} is used to define conditions involving multiple restrictions, grouped by
+ * logical constructs such as {@link Type#ALL} or {@link Type#ANY}. This interface enables the composition
+ * of restrictions, supporting operations like negation and querying the structure of the composite restriction.
+ * Composite restrictions are immutable. Any operation that modifies the state of a restriction,
+ * such as negation, will return a new {@code CompositeRestriction} instance without altering the original.
+ * This ensures thread safety and predictable behavior.
+ *
+ * <p>Example usage:
+ * // TODO add example usage
+ * @param <T> the entity type being restricted
+ */
 public interface CompositeRestriction<T> extends Restriction<T> {
+
+    /**
+     * Checks whether this composite restriction has been negated.
+     * <p>
+     * Negation inverts the meaning of the composite restriction. For example:
+     * <ul>
+     *   <li>A composite restriction of type {@link Type#ALL} negated becomes "NOT (ALL conditions are satisfied)."</li>
+     *   <li>A composite restriction of type {@link Type#ANY} negated becomes "NOT (ANY condition is satisfied)."</li>
+     * </ul>
+     * </p>
+     * //TODO does it make sense?
+     * @return {@code true} if the composite restriction is negated, otherwise {@code false}
+     */
     boolean isNegated();
 
+    /**
+     * Returns a new {@code CompositeRestriction} instance with the negated condition.
+     * Negation inverts the meaning of this composite restriction while retaining its structure.
+     * For example, a composite restriction of type {@link Type#ALL} will result in a new restriction
+     * representing "NOT (ALL conditions)." Similarly, for {@link Type#ANY}, it will represent
+     * "NOT (ANY condition)."
+     * //TODO does it make sense?
+     * @return a new negated {@code CompositeRestriction} instance
+     */
     @Override
     CompositeRestriction<T> negate();
 
+    /**
+     * Retrieves the list of individual restrictions that make up this composite restriction.
+     * The returned list contains the individual restrictions, in the order they were added.
+     * These restrictions can be used to examine or analyze the structure of the composite restriction.
+     *
+     * @return a list of individual {@link Restriction} instances that form this composite restriction
+     */
     List<Restriction<T>> restrictions();
 
+    /**
+     * Retrieves the type of the composite restriction, indicating how the individual restrictions
+     * are evaluated.
+     * The type can be one of the following:
+     * <ul>
+     *   <li>{@link Type#ALL}: All conditions in the composite restriction must be satisfied.</li>
+     *   <li>{@link Type#ANY}: At least one condition in the composite restriction must be satisfied.</li>
+     * </ul>
+     *
+     * @return the {@link Type} of the composite restriction
+     */
     Type type();
 
+    /**
+     * Determines how individual restrictions within a composite restriction are evaluated.
+     * The type specifies whether all conditions must be satisfied ({@link #ALL}) or at least
+     * one condition must be satisfied ({@link #ANY}).
+     */
     enum Type {
+        /**
+         * All conditions in the composite restriction must be satisfied.
+         */
         ALL,
+
+        /**
+         * At least one condition in the composite restriction must be satisfied.
+         */
         ANY
     }
 }

api/src/main/java/jakarta/data/Operator.java

@@ -17,22 +17,76 @@
  */
 package jakarta.data;
 
+
+/**
+ * Defines comparison operators for constructing query restrictions.
+ * These operators are used to specify conditions in queries, such as comparisons,
+ * inclusion, exclusion, and pattern matching. Each operator can be dynamically negated
+ * using the {@link #negate()} method to create logically inverted conditions,
+ * enabling flexible query construction.
+ */
 public enum Operator {
+    /**
+     * Tests for equality (e.g., field = value).
+     */
     EQUAL,
+
+    /**
+     * Tests if a value is greater than the field (e.g., field > value).
+     */
     GREATER_THAN,
+
+    /**
+     * Tests if a value is greater than or equal to the field (e.g., field >= value).
+     */
     GREATER_THAN_EQUAL,
+
+    /**
+     * Tests if a field's value is within a set of values (e.g., field IN (values)).
+     */
     IN,
+
+    /**
+     * Tests if a value is less than the field (e.g., field < value).
+     */
     LESS_THAN,
+
+    /**
+     * Tests if a value is less than or equal to the field (e.g., field <= value).
+     */
     LESS_THAN_EQUAL,
+
+    /**
+     * Matches a value against a pattern (e.g., field LIKE value).
+     */
     LIKE,
+
+    /**
+     * Tests for inequality (e.g., field != value).
+     */
     NOT_EQUAL,
+
+    /**
+     * Tests if a field's value is not within a set of values (e.g., field NOT IN (values)).
+     */
     NOT_IN,
+
+    /**
+     * Matches a value against a negated pattern (e.g., field NOT LIKE value).
+     */
     NOT_LIKE;
 
     /**
-     * Returns the operator that is the negation of this operator.
+     * Returns the logical negation of this operator.
+     * Negation inverts the operator's meaning. For example:
+     * <ul>
+     *   <li>{@code EQUAL} becomes {@code NOT_EQUAL}</li>
+     *   <li>{@code IN} becomes {@code NOT_IN}</li>
+     *   <li>{@code GREATER_THAN} becomes {@code LESS_THAN_EQUAL}</li>
+     * </ul>
+     * This is useful for dynamically constructing queries with reversed logic.
      *
-     * @return the operator that is the negation of this operator.
+     * @return the negated operator
      */
     Operator negate() {
         return switch (this) {