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 { public static Phantom empty() {