Javadocs on type pattern matching

Author: prdoyle

boson/src/main/java/works/bosk/boson/mapping/TypeScanner.java

@@ -76,6 +76,13 @@
  * the directive's {@link Directive#spec spec function} will provide a specification
  * that is further {@link JsonValueSpec#specialize specialized} to handle the actual type.
  * <p>
+ * In other words, the specification of which types to handle uses
+ * Java type expressions, interpreted according to {@link DataType#isBindableFrom},
+ * making it relatively intuitive.
+ * You can use {@code String} to match exactly that type,
+ * or you can define a type variable like {@code T extends CharSequence}
+ * and use that.
+ * <p>
  * The scan aggressively follows any types referenced in {@link TypeRefNode}s,
  * so the specifications returned from directives can use those freely,
  * rather than needing to recursively specify every referenced type.

boson/src/main/java/works/bosk/boson/types/DataType.java

@@ -93,8 +93,8 @@ static DataType of(TypeReference<?> ref) {
 	 * handle generics. Note, in particular, that it returns {@code false}
 	 * for boxing and unboxing conversions, as does {@link Class#isAssignableFrom}.
 	 * <p>
-	 * Note that this is neither weaker nor stronger than {@link #isBindableFrom}.
-	 * Type variables will only accept themselves or other type variables
+	 * Note that this is neither weaker nor stronger than {@link #isBindableFrom}:
+	 * type variables will only accept themselves or other type variables
 	 * that are nominally subtypes of them,
 	 * but concrete types can be assigned from subtypes.
 	 */
@@ -103,12 +103,29 @@ default boolean isAssignableFrom(DataType other) {
 	}
 
 	/**
-	 * {@code A.isBindableFrom(B)} if a value of type List<B>
-	 * can be passed to a method expecting List<A>.
+	 * {@code A.isBindableFrom(B)} if there exists a set of <em>bindings</em>
+	 * that would make {@code A} equal to {@code B}.
+	 * Type variables are bound by their name, so two type variables
+	 * with the same name must be bound to the same type;
+	 * wildcards can be bound to any type that conforms to their bounds.
 	 * <p>
-	 * Note that this is neither weaker nor stronger than {@link #isAssignableFrom(DataType)}.
-	 * Type variables will accept types that conform to their bounds,
-	 * but concrete types cannot be assigned from subtypes.
+	 * This "bindable" concept does not correspond to any operation
+	 * in the Java language, but it is powerful and useful for describing
+	 * sets of related types.
+	 * For example, a type {@code List<Set<?>>} is considered bindable from
+	 * {@code List<Set<String>>}, but Java does not consider them
+	 * to match because {@code List<Set<?>>} describes a list of individually homogeneous sets
+	 * that might differ from each other,
+	 * so {@code list.add(Set.of(1,2,3))} would be allowed
+	 * even though this is not a set of {@code String}s.
+	 * Similarly, {@code List<Set<T>>} where {@code T extends CharSequence}
+	 * is bindable from {@code List<Set<String>>},
+	 * but Java does not consider them to match simply because {@code T}
+	 * represents some specific subtype of {@code CharSequence} that might not be {@code String}.
+	 * <p>
+	 * Note that this is neither weaker nor stronger than {@link #isAssignableFrom(DataType)}:
+	 * type variables will accept types that conform to their bounds,
+	 * but concrete types are invariant and don't match subtypes.
 	 */
 	default boolean isBindableFrom(DataType other) {
 		return isBindableFrom(other, IS_BINDABLE, new HashMap<>());
@@ -121,12 +138,12 @@ default boolean isBindableFrom(DataType other) {
 	 * @param freeVariables if false, unbound type variables match only themselves
 	 */
 	record BindableOptions(boolean allowSubtypes, boolean freeVariables){
-		public static final BindableOptions IS_BINDABLE = new BindableOptions(false, true);
-		public static final BindableOptions IS_ASSIGNABLE = new BindableOptions(true, false);
+		static final BindableOptions IS_ASSIGNABLE = new BindableOptions(true, false);
+		static final BindableOptions IS_BINDABLE = new BindableOptions(false, true);
 
 		/**
 		 * Often, whether subtypes are allowed varies during the matching process.
-		 * This lets us assert a new value for that flag while keeping the other the same.
+		 * This lets us assert a new value for that flag while keeping the rest unchanged.
 		 */
 		public BindableOptions withAllowSubtypes(boolean v) {
 			return new BindableOptions(v, this.freeVariables);

boson/src/main/java/works/bosk/boson/types/TypeVariable.java

@@ -13,6 +13,10 @@
  * <p>
  * When processing the bounds, you can always convert them to {@link DataType}s
  * as needed, but be careful to avoid infinite recursion.
+ * <p>
+ * TODO: Consider whether {@link #equals} is right here.
+ * Should two type variables declared in two different places,
+ * but with the same name and bounds, be considered equal?
  */
 public record TypeVariable(String name, List<Type> bounds) implements UnknownType {
 

…/boson/types/DataTypeAssignableTest.java …boson/types/DataTypeConformanceTest.javaboson/src/test/java/works/bosk/boson/types/DataTypeAssignableTest.java renamed to boson/src/test/java/works/bosk/boson/types/DataTypeConformanceTest.java boson/src/test/java/works/bosk/boson/types/DataTypeAssignableTest.java renamed to boson/src/test/java/works/bosk/boson/types/DataTypeConformanceTest.java

@@ -13,7 +13,10 @@
 import static works.bosk.boson.types.DataType.INT;
 import static works.bosk.boson.types.DataType.OBJECT;
 
-public class DataTypeAssignableTest {
+/**
+ * Tests {@link DataType#isAssignableFrom} and {@link DataType#isBindableFrom}.
+ */
+public class DataTypeConformanceTest {
 
 	@Test
 	void simpleSubtype() {
@@ -27,6 +30,8 @@ void simpleSubtype() {
 	void boxing() {
 		// Boxing/unboxing are allowed by assignment conversion (JLS §5.1.7 / §5.2)
 		// but Class.isAssignableFrom returns false for these, so who are we to argue?
+		// Besides, this is useful when we use them in Directives, since typically
+		// code dealing with primitives doesn't want to deal with boxed types.
 		assertFalse(INT.isAssignableFrom(Integer.class));
 		assertFalse(DataType.of(Integer.class).isAssignableFrom(INT));
 	}