Add javadoc to various List-related classes

reactfx/src/main/java/org/reactfx/Observable.java

@@ -13,20 +13,25 @@
  * {@link #observe(Object)} method and removed by the returned
  * {@linkplain Subscription}.
  *
- * In specific subtypes, methods for adding/removing canonical observers may
- * have aliases that are more descriptive for the specific type, for example,
- * in {@link EventStream}, {@linkplain #observe(Object)} is aliased as
- * {@linkplain EventStream#subscribe(java.util.function.Consumer)}, or in
- * {@link Val}, {@linkplain #addObserver(Object)} is aliased as
- * {@linkplain Val#addInvalidationObserver(java.util.function.Consumer)}.
+ * <p>
+ *     In specific subtypes, methods for adding/removing canonical observers may
+ *     have aliases that are more descriptive for the specific type, for example,
+ *     in {@link EventStream}, {@linkplain #observe(Object)} is aliased as
+ *     {@linkplain EventStream#subscribe(java.util.function.Consumer)}, or in
+ *     {@link Val}, {@linkplain #addObserver(Object)} is aliased as
+ *     {@linkplain Val#addInvalidationObserver(java.util.function.Consumer)}.
+ * </p>
+
  *
- * In addition to the canonical observer, subtypes may support adding other
- * observer types. These other observers will be wrapped to "look like" a
- * canonical observer. For example, the canonical observer for
- * {@code Val<T>} is an <em>invalidation observer</em>, which is of type
- * {@code Consumer<? super T>}, which accepts the invalidated value.
- * In addition to this canonical observer, {@linkplain Val} also supports
- * {@link InvalidationListener}s and {@link ChangeListener}s.
+ * <p>
+ *     In addition to the canonical observer, subtypes may support adding other
+ *     observer types. These other observers will be wrapped to "look like" a
+ *     canonical observer. For example, the canonical observer for
+ *     {@code Val<T>} is an <em>invalidation observer</em>, which is of type
+ *     {@code Consumer<? super T>}, which accepts the invalidated value.
+ *     In addition to this canonical observer, {@linkplain Val} also supports
+ *     {@link InvalidationListener}s and {@link ChangeListener}s.
+ * </p>
  *
  * @param <O> observer type accepted by this {@linkplain Observable}
  */

reactfx/src/main/java/org/reactfx/ObservableBase.java

@@ -37,6 +37,7 @@ protected ObservableBase() {
      * This method is called when the number of observers goes from 0 to 1.
      * This method is called <em>before</em> {@link #newObserver(Object)}
      * is called for the first observer.
+     *
      * @return subscription used to stop observing inputs. The subscription
      * is unsubscribed (i.e. input observation stops) when the number of
      * observers goes down to 0.

reactfx/src/main/java/org/reactfx/ProperObservable.java

@@ -8,6 +8,7 @@
  * {@link ProxyObservable}, which registers observers with an underlying
  * {@linkplain Observable}, and unlike {@link RigidObservable}, which does
  * not produce any notifications.
+ *
  * @param <O> observer type accepted by this {@linkplain Observable}
  * @param <T> notification type produced by this {@linkplain Observable}
  */

reactfx/src/main/java/org/reactfx/collection/ListChange.java

@@ -1,6 +1,10 @@
 package org.reactfx.collection;
 
-
+/**
+ * Stores a list of {@link ListModification}s. Essentially the same as {@link AbstractListModificationSequence} (it
+ * just specifies one of its super-interface's generics). It differs from {@link ListModificationSequence})
+ * in that no "casting" methods exist between that {@code ListModificationSequence}'s two sub-interfaces.
+ */
 public interface ListChange<E>
 extends AbstractListModificationSequence<E, ListModification<? extends E>> {
 }

reactfx/src/main/java/org/reactfx/collection/ListChangeAccumulator.java

@@ -8,6 +8,11 @@
 
 import org.reactfx.util.Lists;
 
+/**
+ * Accumulates {@link QuasiListChange}s until {@link #fetch()} is called, which returns the accumulated list
+ * and then clears its list of accumulations. During the accumulation process, modifications can be added or
+ * {@link #drop(int) dropped} before {@code fetch()} is called.
+ */
 public final class ListChangeAccumulator<E> implements ListModificationSequence<E> {
     private QuasiListChangeImpl<E> modifications = new QuasiListChangeImpl<>();
 
@@ -36,17 +41,29 @@ public boolean isEmpty() {
         return modifications.isEmpty();
     }
 
+    /**
+     * Returns the current list of accumulated {@link QuasiListModification}s and then sets its
+     * list of accumulated changes to an empty list.
+     */
     public QuasiListChange<E> fetch() {
         QuasiListChange<E> res = modifications;
         modifications = new QuasiListChangeImpl<>();
         return res;
     }
 
+    /**
+     * Clears out the list of accumulated {@link QuasiListModification}s from index 0 to index {@code n}. In other
+     * words {@code modifications.subList(0, n).clear()}.
+     */
     public ListChangeAccumulator<E> drop(int n) {
         modifications.subList(0, n).clear();
         return this;
     }
 
+    /**
+     * Adds the {@link QuasiListModification} to the list of accumulated modifications and combines overlapping
+     * modifications into one.
+     */
     public ListChangeAccumulator<E> add(QuasiListModification<? extends E> mod) {
         if(modifications.isEmpty()) {
             modifications.add(mod);

reactfx/src/main/java/org/reactfx/collection/ListModification.java

@@ -7,10 +7,19 @@
 
 import org.reactfx.util.Lists;
 
+/**
+ * A sub-interface of {@link ListModificationLike} that holds a reference to the observable list in which the
+ * modification occurred and whose {@link #getAddedSubList()} method returns a sublist view of
+ * the original observable list. Such sublist is valid only until the next list modification.
+ */
 public interface ListModification<E> extends ListModificationLike<E> {
 
     List<? extends E> getAddedSubList();
 
+    /**
+     * Trims the common prefix and suffix of the {@link #getRemoved()} and {@link #getAddedSubList()} using
+     * {@link Lists#commonPrefixSuffixLengths(List, List)}.
+     */
     ListModification<E> trim();
 
     default MaterializedListModification<E> materialize() {

reactfx/src/main/java/org/reactfx/collection/ListModificationSequence.java

@@ -6,7 +6,9 @@
 import org.reactfx.util.Lists;
 
 /**
- * Common supertype for {@link QuasiListChange} and {@link ListChangeAccumulator}.
+ * Common supertype for {@link QuasiListChange} and {@link ListChangeAccumulator} that has methods
+ * for "casting" one type to another. Note: these casts might be destructive. See the javadoc of
+ * {@link #asListChange()} and {@link #asListChangeAccumulator()}.
  *
  * @param <E> type of list elements
  */
@@ -28,11 +30,22 @@ public interface ListModificationSequence<E>
     ListChangeAccumulator<E> asListChangeAccumulator();
 }
 
+/**
+ * A sequence of {@link ListModificationLike list modifications}. One can get the list of the modifications via
+ * {@link #getModifications()}, their {@link #getModificationCount() number of modifications}, and
+ * {@link #iterator() iterate over those modifications}.
+ */
 interface AbstractListModificationSequence<E, M extends ListModificationLike<? extends E>>
 extends Iterable<M> {
 
+    /**
+     * Gets the {@link ListModificationLike list modifications}
+     */
     List<? extends M> getModifications();
 
+    /**
+     * Iterates over {@link #getModifications()}
+     */
     @Override
     default Iterator<M> iterator() {
         return Lists.readOnlyIterator(getModifications());