Finished Javadoc.

Author: nicolaiparlog

src/org/codefx/libfx/nesting/AbstractNestingBuilderOnObservable.java

@@ -17,12 +17,12 @@
  * nesting steps) and can build a {@link Nesting} from it.
  * <p>
  * Subclasses must not allow nesting if type parameter {@code O} does not also implement {@link ObservableValue}! (Which
- * wouldn't make sense, anyhow, because then no value would be available for the nesting step.)
+ * wouldn't make sense anyhow because then no value would be available for the nesting step.)
  *
  * @param <T>
  *            the type of the wrapped value
  * @param <O>
- *            the type of observable this builder can build;
+ *            the type of {@link Observable} this builder uses as an inner observable
  */
 abstract class AbstractNestingBuilderOnObservable<T, O extends Observable> {
 

src/org/codefx/libfx/nesting/AbstractNestingBuilderOnObservableValue.java

@@ -1,5 +1,6 @@
 package org.codefx.libfx.nesting;
 
+import javafx.beans.Observable;
 import javafx.beans.value.ChangeListener;
 import javafx.beans.value.ObservableValue;
 
@@ -12,7 +13,7 @@
  * @param <T>
  *            the type of the wrapped value
  * @param <O>
- *            the type of observable this builder can build
+ *            the type of {@link Observable} this builder uses as an inner observable
  */
 abstract class AbstractNestingBuilderOnObservableValue<T, O extends ObservableValue<T>>
 		extends AbstractNestingBuilderOnObservable<T, O> {

src/org/codefx/libfx/nesting/AbstractNestingBuilderOnProperty.java

@@ -1,5 +1,6 @@
 package org.codefx.libfx.nesting;
 
+import javafx.beans.Observable;
 import javafx.beans.property.Property;
 
 /**
@@ -8,7 +9,7 @@
  * @param <T>
  *            the type of the wrapped value
  * @param <O>
- *            the type of observable this builder can build
+ *            the type of {@link Observable} this builder uses as an inner observable
  */
 abstract class AbstractNestingBuilderOnProperty<T, O extends Property<T>>
 		extends AbstractNestingBuilderOnObservableValue<T, O> {

src/org/codefx/libfx/nesting/BooleanPropertyNestingBuilder.java

@@ -6,7 +6,7 @@
 import org.codefx.libfx.nesting.property.NestedBooleanPropertyBuilder;
 
 /**
- * A builder for all kinds of nested functionality whose innermost value is held by a {@link BooleanProperty}.
+ * A builder for all kinds of nested functionality whose inner observable is a {@link BooleanProperty}.
  */
 public class BooleanPropertyNestingBuilder extends AbstractNestingBuilderOnProperty<Boolean, BooleanProperty> {
 

src/org/codefx/libfx/nesting/DeepNesting.java

@@ -16,7 +16,7 @@
  * the {@link #innerObservableProperty() innerObservable}.
  *
  * @param <O>
- *            the hierarchy's innermost type of {@link Observable}
+ *            the type of the nesting hierarchy's inner {@link Observable}
  */
 @SuppressWarnings("rawtypes")
 final class DeepNesting<O extends Observable> implements Nesting<O> {
@@ -26,9 +26,9 @@ final class DeepNesting<O extends Observable> implements Nesting<O> {
 	/*
 	 * GENERIC TYPES
 	 *
-	 * Because the depth of the nesting is variable, the number of involved types is determined at runtime. This class
-	 * can hence not use generics for type safety. So it uses tons of raw types, which only works out if the
-	 * constructor is called with the correctly typed outer observable and nesting steps.
+	 * Because the depth of the nesting is not fixed, the number of involved types is determined at runtime. This class
+	 * can hence not use generics for type safety. So it uses tons of raw types, which only works out if the constructor
+	 * is called with the correctly typed outer observable and nesting steps.
 	 *
 	 *
 	 * DATA STRUCTURES
@@ -83,7 +83,7 @@ final class DeepNesting<O extends Observable> implements Nesting<O> {
 	private final ChangeListener[] changeListeners;
 
 	/**
-	 * The property holding the current innermost observable.
+	 * The property holding the current inner observable.
 	 */
 	private final Property<Optional<O>> inner;
 

src/org/codefx/libfx/nesting/DoublePropertyNestingBuilder.java

@@ -6,7 +6,7 @@
 import org.codefx.libfx.nesting.property.NestedDoublePropertyBuilder;
 
 /**
- * A builder for all kinds of nested functionality whose innermost value is held by a {@link DoubleProperty}.
+ * A builder for all kinds of nested functionality whose inner observable is a {@link DoubleProperty}.
  */
 public class DoublePropertyNestingBuilder extends AbstractNestingBuilderOnProperty<Number, DoubleProperty> {
 

src/org/codefx/libfx/nesting/FloatPropertyNestingBuilder.java

@@ -6,7 +6,7 @@
 import org.codefx.libfx.nesting.property.NestedFloatPropertyBuilder;
 
 /**
- * A builder for all kinds of nested functionality whose innermost value is held by a {@link FloatProperty}.
+ * A builder for all kinds of nested functionality whose inner observable is a {@link FloatProperty}.
  */
 public class FloatPropertyNestingBuilder extends AbstractNestingBuilderOnProperty<Number, FloatProperty> {
 

src/org/codefx/libfx/nesting/IntegerPropertyNestingBuilder.java

@@ -6,7 +6,7 @@
 import org.codefx.libfx.nesting.property.NestedIntegerPropertyBuilder;
 
 /**
- * A builder for all kinds of nested functionality whose innermost value is held by an {@link IntegerProperty}.
+ * A builder for all kinds of nested functionality whose inner observable is an {@link IntegerProperty}.
  */
 public class IntegerPropertyNestingBuilder extends AbstractNestingBuilderOnProperty<Number, IntegerProperty> {
 

src/org/codefx/libfx/nesting/LongPropertyNestingBuilder.java

@@ -6,7 +6,7 @@
 import org.codefx.libfx.nesting.property.NestedLongPropertyBuilder;
 
 /**
- * A builder for all kinds of nested functionality whose innermost value is held by a {@link LongProperty}.
+ * A builder for all kinds of nested functionality whose inner observable is a {@link LongProperty}.
  */
 public class LongPropertyNestingBuilder extends AbstractNestingBuilderOnProperty<Number, LongProperty> {
 

src/org/codefx/libfx/nesting/Nesting.java

@@ -7,23 +7,55 @@
 import javafx.beans.value.ObservableValue;
 
 /**
- * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues}; its
- * {@link #innerObservableProperty() innerObservable} property always contains the current innermost {@link Observable}
- * in that hierarchy as an {@link Optional}. If some observable or its value were null, {@code innerObservableProperty}
- * contains {@link Optional#empty()}.
+ * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues} and its
+ * {@link #innerObservableProperty() innerObservable} property always contains the current innermost {@code Observable}
+ * in that hierarchy as an {@link Optional}. A {@code Nesting} can be used as a basic building block for other nested
+ * functionality.
  * <p>
- * Nestings will usually be implemented such that they eagerly evaluate the nested observables.
+ * <h2>Nesting Hierarchy</h2> A nesting hierarchy is composed of some {@code ObservableValues}, often simply called
+ * <b>observables</b>, and <b>nesting steps</b> which lead from one observable to the next.
+ * <p>
+ * At the top of the hierarchy stands one of the observables, the so called <b>outer observable</b>. A nesting step will
+ * use its value to return the next observable. The next step will use that observable's value to return the next
+ * observable and so on. All observables returned by nesting steps are called <b>nested observables</b>. Finally and
+ * perhaps most importantly, the last step will lead to the hierarchy's <b>inner observable</b>.
+ * <p>
+ * As nesting steps require a value to be accessible, all observables on which a step is used must provide a value.
+ * Hence they must all implement {@link ObservableValue} (of {@code T}, where {@code T} is no primitive type wrapper or
+ * {@code String}). No step is used on the inner observable so it suffices that it implements {@link Observable}.
+ * <p>
+ * <h3>Example</h3> Consider a class {@code Employee} which has an {@code Property<Address> address}, where
+ * {@code Address} has a {@code StringProperty streetName}. There might be a {@code Property<Emplyee> currentEmployee},
+ * which always holds the current employee.
+ * <p>
+ * In this case the hierarchy would be {@code currentEmployee -> address -> streetName} where {@code currentEmployee} is
+ * the outer observable and {@code address} and {@code streetName} are nested observables. Additionally,
+ * {@code streetName} is the inner observable.
+ * <p>
+ * <h2>Present or Missing Inner Observable</h2> If all steps return non-null observables and none of them contains null,
+ * the inner observable can be computed and will be contained in the {@link #innerObservableProperty() innerObservable}
+ * property. In this case it is said to be <b>present</b>. The same is true if only the inner observable contains null.
+ * <p>
+ * If any nesting step returns null or any observable except the inner contains null as a value, the nesting hierarchy
+ * can not be completely computed. The inner observable is said to be <b>missing</b> and the {@code innerObservable}
+ * property contains {@link Optional#empty()}.
+ * <p>
+ * <h2>Evaluation</h2> Nestings will usually be implemented such that they eagerly evaluate the nested observables.
+ * <p>
+ * <h2>Build</h2> Instances of {@code Nesting} can be created with dedicated builders. These can be obtained by starting
+ * with one of the methods in {@link Nestings}. More details can be found there.
  *
+ * @see Nestings
  * @param <O>
- *            the type of the hierarchy's innermost {@link Observable}
+ *            the type of the nesting hierarchy's inner {@link Observable}
  */
 public interface Nesting<O extends Observable> {
 
 	/**
-	 * A property holding the current innermost observable in the hierarchy as an optional. If some observable or its
-	 * value were null, this contains {@link Optional#empty()}.
+	 * A property holding the current inner observable in the hierarchy as an optional. If some observable or its value
+	 * were null, this contains {@link Optional#empty()}.
 	 *
-	 * @return the innermost {@link ObservableValue} in an {@link Optional}
+	 * @return the inner {@link Observable} in an {@link Optional}
 	 */
 	ReadOnlyProperty<Optional<O>> innerObservableProperty();