Adds documentation

pom.xml

@@ -80,6 +80,7 @@
     <!-- maven-javadoc-plugin properties -->
     <bottom><![CDATA[Copyright &copy; ${project.inceptionYear}&ndash;{currentYear}, <a href="${project.organization.url}" target="_top">${project.organization.name}</a>. All rights reserved.]]></bottom>
     <doctitle>&lt;a href="${project.url}" target="_top"&gt;&lt;span style="font-family:Lobster, cursive;"&gt;µb&lt;/span&gt; ${project.artifactId}&lt;/a&gt; ${project.version}</doctitle>
+    <links>https://microbean.github.io/microbean-assign/apidocs/,https://microbean.github.io/microbean-construct/apidocs/,https://microbean.github.io/microbean-qualifier/apidocs/</links>
     <sourcetab>2</sourcetab>
 
     <!-- maven-release-plugin properties -->
@@ -134,9 +135,9 @@
       <dependency>
         <groupId>org.microbean</groupId>
         <artifactId>microbean-assign</artifactId>
-        <version>0.0.1-SNAPSHOT</version>
+        <version>0.0.1</version>
       </dependency>
-      
+
       <dependency>
         <groupId>org.microbean</groupId>
         <artifactId>microbean-construct</artifactId>

src/main/java/org/microbean/event/EventQualifiersMatcher.java

@@ -24,12 +24,56 @@
 import static org.microbean.assign.Qualifiers.defaultQualifiers;
 import static org.microbean.assign.Qualifiers.qualifiers;
 
-public final class EventQualifiersMatcher implements Matcher<Collection<? extends NamedAttributeMap<?>>, Collection<? extends NamedAttributeMap<?>>> {
+/**
+ * A {@link Matcher} encapsulating <a
+ * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">CDI-compatible event
+ * qualifier matching rules</a>.
+ *
+ * @author <a href="https://about.me/lairdnelson/" target="_top">Laird Nelson</a>
+ *
+ * @see #test(Collection, Collection)
+ */
+public final class EventQualifiersMatcher
+  implements Matcher<Collection<? extends NamedAttributeMap<?>>, Collection<? extends NamedAttributeMap<?>>> {
+
+
+  /*
+   * Constructors.
+   */
 
+
+  /**
+   * Creates a new {@link EventQualifiersMatcher}.
+   */
   public EventQualifiersMatcher() {
     super();
   }
 
+
+  /*
+   * Instance methods.
+   */
+
+
+  /**
+   * Returns {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection)
+   * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection
+   * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code
+   * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain
+   * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes}.
+   *
+   * @param receiverAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null}
+   *
+   * @param payloadAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null}
+   *
+   * @return {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection)
+   * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection
+   * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code
+   * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain
+   * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes}
+   *
+   * @exception NullPointerException if either argument is {@code null}
+   */
   @Override // Matcher<Collection<? extends NamedAttributeMap<?>>, Collection<? extends NamedAttributeMap<?>>>
   public final boolean test(final Collection<? extends NamedAttributeMap<?>> receiverAttributes,
                             final Collection<? extends NamedAttributeMap<?>> payloadAttributes) {

src/main/java/org/microbean/event/EventTypeMatcher.java

@@ -32,12 +32,65 @@
 
 import org.microbean.construct.Domain;
 
+/**
+ * An {@link AbstractTypeMatcher} encapsulating <a
+ * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">CDI-compatible event type
+ * matching rules</a>.
+ *
+ * @author <a href="https://about.me/lairdnelson/" target="_top">Laird Nelson</a>
+ *
+ * @see #test(TypeMirror, TypeMirror)
+ */
 public final class EventTypeMatcher extends AbstractTypeMatcher {
 
+
+  /*
+   * Constructors.
+   */
+
+
+  /**
+   * Creates a new {@link EventTypeMatcher}.
+   *
+   * @param domain a {@link Domain}; must not be {@code null}
+   *
+   * @exception NullPointerException if {@code domain} is {@code null}
+   *
+   * @see Domain
+   */
   public EventTypeMatcher(final Domain domain) {
     super(domain);
   }
 
+
+  /*
+   * Instance methods.
+   */
+
+
+  /**
+   * Returns {@code true} if and only if the supplied {@code payload} argument (normally an <dfn>event type</dfn>) <a
+   * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution"><em>matches</em></a> the
+   * supplied {@code receiver} argument (normally an <dfn>observed event type</dfn>), according to the rules defined by
+   * <a href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">section 2.8.3 of the
+   * CDI specification</a>.
+   *
+   * @param receiver the left hand side of an event type assignment (normally an observed event type); must not be
+   * {@code null}
+   *
+   * @param payload the right hand side of an event type assignment (normally an event type); must not be {@code null}
+   *
+   * @return {@code true} if and only if the supplied {@code payload} argument <a
+   * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">matches</a> the supplied
+   * {@code receiver} argument, according to the rules defined by <a
+   * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">section 2.8.3 of the CDI
+   * specification</a>; {@code false} otherwise
+   *
+   * @exception NullPointerException if either argument is {@code null}
+   *
+   * @exception IllegalArgumentException if either type is any type other than an {@linkplain TypeKind#ARRAY array
+   * type}, a {@link TypeKind#isPrimitive() primitive type}, or a {@linkplain TypeKind#DECLARED declared type}
+   */
   @Override // Matcher<TypeMirror, TypeMirror>
   public final boolean test(final TypeMirror receiver, final TypeMirror payload) {
     // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution
@@ -230,6 +283,12 @@ private final boolean assignable(final DeclaredType receiver, final DeclaredType
     }; // end switch(payload)
   }
 
+
+  /*
+   * Static methods.
+   */
+
+
   // Returns a new IllegalArgumentException describing an illegal payload type.
   private static IllegalArgumentException illegalPayload(final TypeMirror payload) {
     return new IllegalArgumentException("Illegal payload kind: " + payload.getKind() + "; payload: " + payload);

src/main/java/org/microbean/event/EventTypes.java

@@ -34,7 +34,15 @@
 
 import static java.lang.System.Logger.Level.WARNING;
 
-// Experimental and basically located in the wrong package and module.
+/**
+ * A utility for working with <dfn>event types</dfn>.
+ *
+ * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
+ *
+ * @see #eventTypes(TypeMirror)
+ *
+ * @see #legalEventType(TypeMirror)
+ */
 public final class EventTypes extends Types {
 
 
@@ -51,6 +59,13 @@ public final class EventTypes extends Types {
    */
 
 
+  /**
+   * Creates a new {@link EventTypes}.
+   *
+   * @param domain a {@link Domain}; must not be {@code null}
+   *
+   * @exception NullPointerException if {@code domain} is {@code null}
+   */
   public EventTypes(final Domain domain) {
     super(domain);
   }
@@ -61,6 +76,25 @@ public EventTypes(final Domain domain) {
    */
 
 
+  /**
+   * Returns an immutable {@link List} of {@linkplain #legalEventType(TypeMirror) legal event types} that the supplied
+   * {@link TypeMirror} bears.
+   *
+   * <p>The returned {@link List} may be empty.</p>
+   *
+   * @param t a {@link TypeMirror}; must not be {@code null}
+   *
+   * @return an immutable {@link List} of {@linkplain #legalEventType(TypeMirror) legal event types} that the supplied
+   * {@link TypeMirror} bears; never {@code null}
+   *
+   * @exception NullPointerException if {@code t} is {@code null}
+   *
+   * @microbean.nullability This method never returns {@code null}.
+   *
+   * @microbean.idempotency This method is idempotent and returns determinate values.
+   *
+   * @microbean.threadsafety This method is safe for concurrent use by multiple threads.
+   */
   public final List<? extends TypeMirror> eventTypes(final TypeMirror t) {
     // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types
     if (t.getKind() == TypeKind.DECLARED) {
@@ -84,6 +118,32 @@ public final List<? extends TypeMirror> eventTypes(final TypeMirror t) {
    */
 
 
+  /**
+   * Returns {@code true} if and only if the supplied {@link TypeMirror} is a <dfn>legal event type</dfn>.
+   *
+   * <p>Legal event types are, exactly:</p>
+   *
+   * <ol>
+   *
+   * <li>{@linkplain TypeKind#ARRAY Array} types whose {@linkplain ArrayType#getComponentType() component type}s are
+   * legal event types</li>
+   *
+   * <li>{@linkplain TypeKind#DECLARED Declared} types that contain no {@linkplain TypeKind#WILDCARD wildcard type}s for
+   * every level of containment</li>
+   *
+   * </ol>
+   *
+   * @param t a {@link TypeMirror}; must not be {@code null}
+   *
+   * @return {@code true} if and only if {@code t} is a legal bean type; {@code false} otherwise
+   *
+   * @exception NullPointerException if {@code t} is {@code null}
+   *
+   * @microbean.idempotency This method is idempotent and deterministic.
+   *
+   * @microbean.threadsafety This method itself is safe for concurrent use by multiple threads, but {@link TypeMirror}
+   * implementations and {@link Domain} implementations may not be safe for such use.
+   */
   public static final boolean legalEventType(final TypeMirror t) {
     // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types
     return switch (t.getKind()) {
@@ -128,6 +188,24 @@ public static final boolean legalEventType(final TypeMirror t) {
 
   }
 
+  /**
+   * Returns {@code true} if and only if the supplied {@link TypeMirror} is a <dfn>legal observed event type</dfn>.
+   *
+   * <p>A legal observed event type is <a
+   * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types">any Java type
+   * that a method parameter may bear</a>.
+   *
+   * @param t a {@link TypeMirror}; must not be {@code null}
+   *
+   * @return {@code true} if and only if {@code t} is a legal observed event type; {@code false} otherwise
+   *
+   * @exception NullPointerException if {@code t} is {@code null}
+   *
+   * @microbean.idempotency This method is idempotent and deterministic.
+   *
+   * @microbean.threadsafety This method itself is safe for concurrent use by multiple threads, but {@link TypeMirror}
+   * implementations and {@link Domain} implementations may not be safe for such use.
+   */
   public static final boolean legalObservedEventType(final TypeMirror t) {
     // https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#event_types_and_qualifier_types
     // "Any Java type [that a method parameter element may bear] may be an observed event type."
@@ -137,5 +215,4 @@ public static final boolean legalObservedEventType(final TypeMirror t) {
     };
   }
 
-
 }