review

Author: triceo

core/src/main/java/ai/timefold/solver/core/preview/api/move/MutableSolutionView.java

@@ -131,7 +131,6 @@ <Entity_, Value_> void unassignValue(PlanningListVariableMetaModel<Solution_, En
      *        Acceptable values range from zero to one less than list size.
      *        All values after the index are shifted to the left.
      * @return the removed value
-     * @throws IndexOutOfBoundsException if the index is out of bounds
      */
     <Entity_, Value_> Value_ unassignValue(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
             Entity_ entity, int index);
@@ -171,28 +170,29 @@ <Entity_, Value_> void changeVariable(PlanningVariableMetaModel<Solution_, Entit
      *        All values at or after the index are shifted to the right.
      *        To append to the end of the list, use the list size as index.
      * @return the value that was moved
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceEntity == destinationEntity
      */
     <Entity_, Value_> Value_ moveValueBetweenLists(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
             Entity_ sourceEntity, int sourceIndex, Entity_ destinationEntity, int destinationIndex);
 
     /**
-     * Replaces a value from one entity's {@link PlanningListVariable planning list variable} with another.
-     * The value is removed from the replacementIndex, shifting all later values to the left.
-     * The value is then added at the sourceIndex, replacing the pre-existing value and unassigning it.
-     * This means that the replacement list will be one item shorter after the move.
+     * Replaces a value in one entity's {@link PlanningListVariable planning list variable} with a value taken from another.
+     * The value is removed from {@code replacementEntity} at {@code replacementIndex}, shifting all later values to the left.
+     * The removed value is then assigned to {@code sourceEntity} at {@code sourceIndex},
+     * overwriting the pre-existing value and unassigning it.
+     * This means that the replacementEntity's list will be one item shorter after the move,
+     * while the sourceEntity's list size remains unchanged.
      *
      * @param variableMetaModel Describes the variable to be changed.
-     * @param sourceEntity The entity in which the value will be replaced.
-     * @param sourceIndex The index in the source entity's list variable which contains the value to be replaced;
-     *        Acceptable values range from zero to one less than list size.
-     * @param replacementEntity The entity from which the value will be taken.
-     * @param replacementIndex The index in the replacementEntity's list variable which contains the value to be moved;
-     *        Acceptable values range from zero to one less than list size.
+     * @param sourceEntity The entity in which the value at {@code sourceIndex} will be replaced (overwritten).
+     * @param sourceIndex The index in the source entity's list variable whose current value will be overwritten;
+     *        Acceptable values range from zero to one less than the source list size.
+     * @param replacementEntity The entity from which the replacement value will be taken and removed.
+     * @param replacementIndex The index in the replacementEntity's list variable which contains the value to be moved and
+     *        removed;
+     *        Acceptable values range from zero to one less than the replacement list size.
      *        All values at or after the index are shifted to the left.
      * @return the value that was replaced
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceEntity == replacementEntity;
      *         use {@link #replaceValueInList(PlanningListVariableMetaModel, Object, int, int)} instead.
      * @see #moveValueBetweenLists(PlanningListVariableMetaModel, Object, int, Object, int) Similar operation that moves the
@@ -275,7 +275,6 @@ <Entity_, Value_> Value_ replaceValueInList(PlanningListVariableMetaModel<Soluti
      *        The offset must not be zero.
      *        The offset must not move the value out of bounds.
      * @return the value that was moved
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if sourceIndex == destinationIndex
      * @see #moveValueInList(PlanningListVariableMetaModel, Object, int, int) Equivalent operation using index arithmetics
      *      instead of offset calculation.
@@ -302,7 +301,6 @@ default <Entity_, Value_> Value_ shiftValue(PlanningListVariableMetaModel<Soluti
      * @param rightEntity The second entity whose variable value is to be swapped.
      * @param rightIndex The index in the right entity's list variable which contains the other value to be swapped;
      *        Acceptable values range from zero to one less than list size.
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if leftEntity == rightEntity while leftIndex == rightIndex
      */
     <Entity_, Value_> void swapValuesBetweenLists(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,
@@ -317,7 +315,6 @@ <Entity_, Value_> void swapValuesBetweenLists(PlanningListVariableMetaModel<Solu
      *        Acceptable values range from zero to one less than list size.
      * @param rightIndex The index in the entity's list variable which contains the other value to be swapped;
      *        Acceptable values range from zero to one less than list size.
-     * @throws IndexOutOfBoundsException if either index is out of bounds
      * @throws IllegalArgumentException if leftIndex == rightIndex
      */
     <Entity_, Value_> void swapValuesInList(PlanningListVariableMetaModel<Solution_, Entity_, Value_> variableMetaModel,