Phantom javadocs

bosk-core/src/main/java/works/bosk/Phantom.java

@@ -3,9 +3,19 @@
 /**
  * Used to create a thing that can be referenced (eg. as the domain
  * of a {@link Listing}) but that is not actually serialized or instantiated.
- *
- * <p>
  * Behaves like an {@link java.util.Optional Optional} that is always empty.
+ * <p>
+ * Why would anyone want such a thing?
+ * <p>
+ * The domain of a {@link Listing} plays a role somewhat like a datatype:
+ * it indicates the nature of the values it can reference.
+ * Often, the domain is a {@link Catalog} that explicitly lists all the allowed values,
+ * but sometimes you don't want to list all the possible values in the bosk state;
+ * you just want to be clear about what the allowed values are.
+ * For example, there may be a large or infinite number of possible values;
+ * or there might be nothing to store about the value besides its ID.
+ * In that case, you can use a <code>Phantom&lt;Catalog&lt;T>></code>,
+ * and reference that as your domain.
  */
 public final class Phantom<T> {
 	public static <T> Phantom<T> empty() {