diff --git a/bosk-core/src/main/java/works/bosk/Phantom.java b/bosk-core/src/main/java/works/bosk/Phantom.java index e2d88414..ddf03725 100644 --- a/bosk-core/src/main/java/works/bosk/Phantom.java +++ b/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. - * - *
* Behaves like an {@link java.util.Optional Optional} that is always empty. + *
+ * Why would anyone want such a thing? + *
+ * 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 Phantom<Catalog<T>>
,
+ * and reference that as your domain.
*/
public final class Phantom