Improve documentation to include introduction of "missing behavior"

Author: nicolaiparlog

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

@@ -8,10 +8,11 @@
 
 /**
  * <p>
- * 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.
+ * A nesting encapsulates a hierarchy of nested {@link ObservableValue ObservableValues}.
+ * <p>
+ * 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.
  * <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>
@@ -24,7 +25,7 @@
  * Hence they must all implement {@link ObservableValue ObservableValue}. No step is used on the inner observable so it
  * suffices that it implements {@link Observable}.
  * <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},
+ * {@code Address} has a {@code StringProperty streetName}. There might be a {@code Property<Employee> currentEmployee},
  * which always holds the current employee.
  * <p>
  * In this case the hierarchy would be {@code currentEmployee -> address -> streetName} where {@code currentEmployee} is

src/main/java/org/codefx/libfx/nesting/property/NestedProperty.java

@@ -6,24 +6,32 @@
 
 /**
  * <p>
- * A {@link Property} which is based on a {@link Nesting}. Simply put, this property is always bound to the nesting's
- * inner observable (more precisely, it is bound to the {@link Property} instance contained in the optional value held
- * by the nesting's {@link Nesting#innerObservableProperty() innerObservable} property).
- * <h2>Inner Observable's Value Changes</h2> This property is bound to the nesting's inner observable. So when that
- * observable's value changes, so does this property.
+ * A {@link Property} which is based on a {@link Nesting}.
+ * <p>
+ * Simply put, this property is always bound to the nesting's inner observable (more precisely, it is bound to the
+ * {@link Property} instance contained in the optional value held by the nesting's
+ * {@link Nesting#innerObservableProperty() innerObservable} property).
+ * <h2>Value Changes</h2> This property is bidirectionally bound to the nesting's inner observable. So when that
+ * observable's value changes, so does this property's value and vice versa.
  * <h2>Inner Observable Is Replaced</h2> When the nesting's inner observable is replaced by a present observable, this
  * nested property's value changes to the new observable's value. Like all other value changes this one also results in
  * calling invalidation and change listeners.
- * <p>
- * If the new observable is missing, this property stays unbound and keeps its value (and hence no listener is called).
- * <h2>Inner Observable is Missing</h2> It is possible that a nesting's inner observable is missing (see comment on
+ * <h2>Missing Inner Observable</h2> It is possible that a nesting's inner observable is missing (see comment on
  * {@link Nesting}). In that case the {@link NestedProperty#innerObservablePresentProperty() innerObservablePresent}
- * property is false and changes made to this property's value can not be propagated to another property.
- * <p>
- * If the inner observable changes back to a present value, everything said above applies. This implies that when the
- * nested property's value changed while the inner observable was missing, these changes are replaced by the new
- * observable's value when one is set. Since this property's change listeners are called, the replaced value can be
- * caught there before it gets lost. TODO add comments explaining what happens when inner observable goes missing
+ * property is false. How else the nested property behaves depends on its configuration which was determined when it was
+ * build.
+ * <h3>When Inner Observable Goes Missing</h3> When the inner observable goes missing, the nested property will either
+ * keep its value (this is the default behavior) or change to a value which was determined at build time. This can be
+ * done with the {@code onInnerObservableMissing...} methods on the nested property builder (e.g.
+ * {@link NestedObjectPropertyBuilder#onInnerObservableMissingSetDefaultValue() onInnerObservableMissingSetDefaultValue}
+ * ).
+ * <h3>Update While Inner Observable Is Missing</h3> When a value is set on the nested property while the inner
+ * observable is missing, it can not be propagated anywhere. For this reason the default behavior is to throw an
+ * exception. Alternatively the property can hold new values until a new inner observable is found (with
+ * {@link NestedObjectPropertyBuilder#onUpdateWhenInnerObservableMissingAcceptValues()
+ * onUpdateWhenInnerObservableMissingAcceptValues}). The property will then be bound to the new observable and hence
+ * forget the intermediate value. (Since this property's change listeners are called, the replaced value can be caught
+ * there before it gets lost.)
  *
  * @param <T>
  *            the type of the value wrapped by the property