Documented package 'org.codefx.libfx.listener.handle'.

Author: nicolaiparlog

src/main/java/org/codefx/libfx/listener/handle/ListenerHandleBuilder.java

@@ -5,7 +5,8 @@
 import java.util.function.BiConsumer;
 
 /**
- * A builder for a {@link ListenerHandle}.
+ * A builder for a {@link ListenerHandle}. Note that it is abstract enough to be used for all kinds of
+ * observable/listener relation and not just for those occurring in JavaFX.
  * <p>
  * The created handle manages whether the listener is currently attached. The functions specified to
  * {@link #onAttach(BiConsumer)} and {@link #onDetach(BiConsumer)} are only called when necessary. This is the case
@@ -16,7 +17,8 @@
  * This implies that they can be stateless functions which simply add and remove the listener. The functions are called
  * with the observable and listener specified during construction.
  * <p>
- * The {@link ListenerHandle} returned by this builder is not yet attached.
+ * The {@link ListenerHandle} returned by this builder is not yet attached, i.e. it does not initially call the
+ * functions give to {@code onAttach} or {@code onDetach}.
  * <p>
  * <h2>Example</h2> A typical use looks like this:
  *

src/main/java/org/codefx/libfx/listener/handle/package-info.java

@@ -1,4 +1,18 @@
 /**
- * TODO
+ * This package provides classes which make it easier to add and remove listeners from observable instances.
+ * <p>
+ * Using the default JavaFX 8 features, it is necessary to store both the observed instance and the listener if the
+ * latter has to be added or removed repeatedly. A {@link org.codefx.libfx.listener.handle.ListenerHandle
+ * ListenerHandle} encapsulates those references and the state whether a listener is currently added or not. It provides
+ * an {@link org.codefx.libfx.listener.handle.ListenerHandle#attach() attach()} and a
+ * {@link org.codefx.libfx.listener.handle.ListenerHandle#detach() detach} method which add or remove the listener.
+ * Redundant calls (i.e. attaching when the listener is already added) are no-ops.
+ * <p>
+ * All features of <b>LibFX</b> which deal with listeners are aware of {@code ListenerHandle}s and respective methods
+ * will return them. For observable classes included in the JDK, the factory
+ * {@link org.codefx.libfx.listener.handle.ListenerHandles ListenerHandles} provides methods to easily create a handle.
+ *
+ * @see org.codefx.libfx.listener.handle.ListenerHandle ListenerHandle
+ * @see org.codefx.libfx.listener.handle.ListenerHandles ListenerHandles
  */
 package org.codefx.libfx.listener.handle;