Improve names and fix comments in equality transforming collections

Author: nicolaiparlog

src/main/java/org/codefx/libfx/collection/transform/EqualityTransformingCollectionBuilder.java

@@ -41,6 +41,8 @@ public class EqualityTransformingCollectionBuilder<E> {
 	private BiPredicate<? super E, ? super E> equals;
 	private ToIntFunction<? super E> hash;
 
+	// #begin CONSTRUCTION
+
 	private EqualityTransformingCollectionBuilder(Class<? super E> outerKeyTypeToken) {
 		this.outerKeyTypeToken = outerKeyTypeToken;
 		// note that the methods from 'Objects' already implement the contract for null-safety
@@ -49,45 +51,43 @@ private EqualityTransformingCollectionBuilder(Class<? super E> outerKeyTypeToken
 		this.hash = Objects::hashCode;
 	}
 
-	// #begin SET PROPERTIES
-
 	/**
-	 * Returns a new builder.
+	 * Returns a new builder for the specified element type.
 	 * <p>
-	 * This method can be called if no type token for the elements can be provided (if it can be, call the preferable
-	 * {@link #forKeyType(Class)} instead). A call might look as follows (for a generic type {@code T}):
-	 *
-	 * <pre>
-	 * EqualityTransformingBuilder.&lt;T&gt; forUnspecifiedKeyType();
-	 * </pre>
+	 * If a type token for the elements can not be provided, call {@link #forKeyTypeUnknown()} instead.
 	 *
 	 * @param <E>
-	 *            the type of elements contained in the set created by the builder
+	 *            the type of elements contained in the created set
+	 * @param keyTypeToken
+	 *            a type token for the elements contained in the created set
 	 * @return a new builder
 	 */
-	public static <E> EqualityTransformingCollectionBuilder<E> forUnspecifiedKeyType() {
-		return new EqualityTransformingCollectionBuilder<>(Object.class);
+	public static <E> EqualityTransformingCollectionBuilder<E> forKeyType(Class<? super E> keyTypeToken) {
+		Objects.requireNonNull(keyTypeToken, "The argument 'keyTypeToken' must not be null.");
+		return new EqualityTransformingCollectionBuilder<>(keyTypeToken);
 	}
 
 	/**
-	 * Returns a new builder to create equality transforming sets for elements of the specified type.
+	 * Returns a new builder for an unknown key type.
 	 * <p>
-	 * If a type token for the keys can not be provided, call {@link #forUnspecifiedKeyType()} instead.
+	 * This is equivalent to calling {@link #forKeyType(Class) forKeyType(Object.class)}. To obtain a builder for
+	 * {@code <E>} you will have to call {@code EqualityTransformingCollectionBuilder.<E> forKeyTypeUnknown()}.
 	 *
 	 * @param <E>
 	 *            the type of elements contained in the set created by the builder
-	 * @param keyTypeToken
-	 *            a type token for the elements contained in the set created by the builder
 	 * @return a new builder
 	 */
-	public static <E> EqualityTransformingCollectionBuilder<E> forKeyType(Class<? super E> keyTypeToken) {
-		Objects.requireNonNull(keyTypeToken, "The argument 'keyTypeToken' must not be null.");
-		return new EqualityTransformingCollectionBuilder<>(keyTypeToken);
+	public static <E> EqualityTransformingCollectionBuilder<E> forKeyTypeUnknown() {
+		return new EqualityTransformingCollectionBuilder<>(Object.class);
 	}
 
+	// #end CONSTRUCTION
+
+	// #begin SET PROPERTIES
+
 	/**
 	 * @param equals
-	 *            a function determining equality of keys; might be called with null keys
+	 *            a function determining equality of elements; might be called with null elements
 	 * @return this builder
 	 */
 	public EqualityTransformingCollectionBuilder<E> withEqualsHandlingNull(BiPredicate<? super E, ? super E> equals) {
@@ -98,7 +98,7 @@ public EqualityTransformingCollectionBuilder<E> withEqualsHandlingNull(BiPredica
 
 	/**
 	 * @param equals
-	 *            a function determining equality of keys; will not be called with null keys
+	 *            a function determining equality of elements; will not be called with null elements
 	 * @return this builder
 	 */
 	public EqualityTransformingCollectionBuilder<E> withEquals(BiPredicate<? super E, ? super E> equals) {
@@ -119,7 +119,7 @@ public EqualityTransformingCollectionBuilder<E> withEquals(BiPredicate<? super E
 
 	/**
 	 * @param hash
-	 *            a function computing the hash code of a key; might be called with null keys
+	 *            a function computing the hash code of an element; might be called with null elements
 	 * @return this builder
 	 */
 	public EqualityTransformingCollectionBuilder<E> withHashHandlingNull(ToIntFunction<? super E> hash) {
@@ -130,7 +130,7 @@ public EqualityTransformingCollectionBuilder<E> withHashHandlingNull(ToIntFuncti
 
 	/**
 	 * @param hash
-	 *            a function computing the hash code of a key; will not be called with null keys
+	 *            a function computing the hash code of an element; will not be called with null elements
 	 * @return this builder
 	 */
 	public EqualityTransformingCollectionBuilder<E> withHash(ToIntFunction<? super E> hash) {
@@ -162,7 +162,7 @@ public EqualityTransformingSet<E> buildSet() {
 	 *            an empty set which is not otherwise referenced
 	 * @return a new instance of {@link EqualityTransformingSet}
 	 */
-	public EqualityTransformingSet<E> buildSetDecorating(Set<Object> emptySet) {
+	public EqualityTransformingSet<E> buildSet(Set<Object> emptySet) {
 		return new EqualityTransformingSet<>(emptySet, outerKeyTypeToken, equals, hash);
 	}
 
@@ -186,7 +186,7 @@ public <V> EqualityTransformingMap<E, V> buildMap() {
 	 *            an empty map which is not otherwise referenced
 	 * @return a new instance of {@link EqualityTransformingMap}
 	 */
-	public <V> EqualityTransformingMap<E, V> buildMapDecorating(Map<Object, Object> emptyMap) {
+	public <V> EqualityTransformingMap<E, V> buildMap(Map<Object, Object> emptyMap) {
 		return new EqualityTransformingMap<>(emptyMap, outerKeyTypeToken, equals, hash);
 	}
 

src/main/java/org/codefx/libfx/collection/transform/EqualityTransformingMap.java

@@ -23,6 +23,8 @@
  * <p>
  * The transformations used by this map preserve object identity of outer keys and values. This means if keys and values
  * are added to this map, an iteration over it will return the same instances.
+ * <p>
+ * {@code EqualityTransformingMap}s are created with a {@link EqualityTransformingCollectionBuilder}.
  *
  * @param <K>
  *            the type of keys maintained by this map
@@ -53,7 +55,7 @@ public final class EqualityTransformingMap<K, V> extends AbstractTransformingMap
 
 	/**
 	 * Creates a new transforming map.
-	 * 
+	 *
 	 * @param innerMap
 	 *            the decorated map; must be empty
 	 * @param outerKeyTypeToken

src/main/java/org/codefx/libfx/collection/transform/EqualityTransformingSet.java

@@ -10,8 +10,7 @@
  * {@link Object#hashCode() hashCode} which are used by the set.
  * <p>
  * It does so by storing the entries in an inner set and providing a transforming view on them. See the
- * {@link org.codefx.libfx.collection.transform package} documentation for general comments on that. Note that instances
- * of {@code EqualityTransformingSet}s are created with a {@link EqualityTransformingCollectionBuilder builder}.
+ * {@link org.codefx.libfx.collection.transform package} documentation for general comments on that.
  * <p>
  * This implementation mitigates the type safety problems by optionally using a token of the outer type to check
  * instances against them. This solves some of the critical situations but not all of them. In those other cases
@@ -23,6 +22,8 @@
  * <p>
  * The transformations used by this set preserve object identity of outer values. This means if values are added to this
  * set, an iteration over it will return the same instances.
+ * <p>
+ * {@code EqualityTransformingSet}s are created with a {@link EqualityTransformingCollectionBuilder}.
  *
  * @param <E>
  *            the type of elements in this set

src/main/java/org/codefx/libfx/collection/transform/TransformingCollectionBuilder.java

@@ -43,7 +43,7 @@ private TransformingCollectionBuilder(Class<? super I> innerTypeToken, Class<? s
 	}
 
 	/**
-	 * Creates a new builder for the specified inner and outer type.
+	 * Returns a new builder for the specified inner and outer type.
 	 *
 	 * @param <I>
 	 *            the inner type of the created transforming collection, i.e. the type of the elements contained in the
@@ -63,7 +63,7 @@ public static <I, O> TransformingCollectionBuilder<I, O> forInnerAndOuterType(
 	}
 
 	/**
-	 * Creates a new builder for unknown inner and outer types.
+	 * Returns a new builder for unknown inner and outer types.
 	 * <p>
 	 * This is equivalent to calling {@link #forInnerAndOuterType(Class, Class) forInnerAndOuterType(Object.class,
 	 * Object.class)}. To obtain a builder for {@code <I, O>} you will have to call

src/main/java/org/codefx/libfx/collection/transform/TransformingMapBuilder.java

@@ -56,7 +56,7 @@ private TransformingMapBuilder(
 	}
 
 	/**
-	 * Creates a new builder for the specified inner and outer key and value types.
+	 * Returns a new builder for the specified inner and outer key and value types.
 	 *
 	 * @param <IK>
 	 *            the inner key type of the created transforming map, i.e. the type of the keys contained in the
@@ -88,7 +88,7 @@ public static <IK, OK, IV, OV> TransformingMapBuilder<IK, OK, IV, OV> forTypes(
 	}
 
 	/**
-	 * Creates a new builder for unknown inner and outer key and value types.
+	 * Returns a new builder for unknown inner and outer key and value types.
 	 * <p>
 	 * This is equivalent to calling {@link #forTypes(Class, Class, Class, Class) forTypes(Object.class, Object.class,
 	 * Object.class, Object.class)}. To obtain a builder for {@code <IK, OK, IV, OV>} you will have to call