Road grading; cleans documentation; adds notion of well-defined annotation sameness

README.md

@@ -36,7 +36,7 @@ dependency:
     Always check https://search.maven.org/artifact/org.microbean/microbean-construct
     for up-to-date available versions.
   -->
-  <version>0.0.22</version>
+  <version>0.0.23</version>
 </dependency>
 ```
 

pom.xml

@@ -253,7 +253,7 @@
             <dependency>
               <groupId>com.puppycrawl.tools</groupId>
               <artifactId>checkstyle</artifactId>
-              <version>13.0.0</version>
+              <version>13.2.0</version>
             </dependency>
           </dependencies>
         </plugin>
@@ -284,7 +284,7 @@
         </plugin>
         <plugin>
           <artifactId>maven-dependency-plugin</artifactId>
-          <version>3.9.0</version>
+          <version>3.10.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-deploy-plugin</artifactId>

src/main/java/module-info.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -13,7 +13,7 @@
  */
 
 /**
- * Provides packages related to Java constructs.
+ * Provides packages related to valid Java language constructs.
  *
  * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
  *

src/main/java/org/microbean/construct/BlockingCompilationTask.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024–2025 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -170,7 +170,7 @@ public final void run() {
       options.add("-verbose");
     }
 
-    // Use an appropriate compiler-supplied thread-safe name table.
+    // Use an appropriate compiler-supplied name table. None are thread-safe, sadly.
     installNameTableOptions(options::add);
 
     // Propagate the current classpath to the compiler environment.
@@ -193,7 +193,7 @@ public final void run() {
                                                     moduleLocations),
                  diagnosticLogger,
                  options,
-                 List.of("java.lang.Deprecated"), // arbitrary, but is always read by the compiler no matter what so incurs no extra reads
+                 List.of("java.lang.Deprecated"), // arbitrary, but always read by the compiler no matter what so incurs no extra reads
                  null); // no compilation units; we're -proc:only
     task.setLocale(locale);
     task.addModules(additionalRootModuleNames);
@@ -252,6 +252,7 @@ private final Set<String> additionalRootModuleNames(final Consumer<? super ReadO
     return Collections.unmodifiableSet(additionalRootModuleNames);
   }
 
+  // (Invoked only by method reference.)
   private final void obtrudeException() {
     // Ideally we'd use CancellationException but see
     // https://github.com/openjdk/jdk/blob/jdk-25%2B3/src/java.base/share/classes/java/util/concurrent/CompletableFuture.java#L2210.

src/main/java/org/microbean/construct/DefaultDomain.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024–2025 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -55,7 +55,7 @@
 import static java.lang.constant.ConstantDescs.BSM_INVOKE;
 
 /**
- * A {@linkplain Domain domain of Java constructs} that can be used at annotation processing time or at runtime.
+ * A {@linkplain Domain domain of valid Java constructs} that can be used at annotation processing time or at runtime.
  *
  * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
  *
@@ -83,13 +83,15 @@ public DefaultDomain() {
    * Creates a new {@link DefaultDomain} <strong>normally for use at annotation processing time</strong>, whose usage
    * type is actually determined by the argument supplied to this constructor.
    *
-   * @param pe a {@link ProcessingEnvironment}; may be {@code null} in which case the return value of an invocation of
-   * {@link Supplier#get()} on the return value of an invocation of {@link RuntimeProcessingEnvironmentSupplier#of()}
-   * will be used instead
+   * @param pe a {@link ProcessingEnvironment}; may be {@code null} (<strong>the expected value for runtime
+   * usage</strong>), in which case the return value of an invocation of {@link Supplier#get()} on the return value of
+   * an invocation of {@link RuntimeProcessingEnvironmentSupplier#of()} will be used instead
    *
    * @see #DefaultDomain(ProcessingEnvironment, Lock)
    *
-   * @see SymbolCompletionLock
+   * @see RuntimeProcessingEnvironmentSupplier#get()
+   *
+   * @see SymbolCompletionLock#INSTANCE
    */
   public DefaultDomain(final ProcessingEnvironment pe) {
     this(pe, null);
@@ -103,9 +105,9 @@ public DefaultDomain(final ProcessingEnvironment pe) {
    *
    * @see #DefaultDomain(ProcessingEnvironment, Lock)
    *
-   * @see RuntimeProcessingEnvironmentSupplier
+   * @see RuntimeProcessingEnvironmentSupplier#get()
    *
-   * @see SymbolCompletionLock
+   * @see SymbolCompletionLock#INSTANCE
    */
   public DefaultDomain(final Lock lock) {
     this(null, lock);
@@ -115,18 +117,18 @@ public DefaultDomain(final Lock lock) {
    * Creates a new {@link DefaultDomain} <strong>normally for use at annotation processing time</strong>, whose usage
    * type is actually determined by the arguments supplied to this constructor.
    *
-   * @param pe a {@link ProcessingEnvironment}; may be {@code null} in which case the return value of an invocation of
-   * {@link Supplier#get()} on the return value of an invocation of {@link RuntimeProcessingEnvironmentSupplier#of()}
-   * will be used instead
+   * @param pe a {@link ProcessingEnvironment}; may be {@code null} (<strong>the expected value for runtime
+   * usage</strong>), in which case the return value of an invocation of {@link Supplier#get()} on the return value of
+   * an invocation of {@link RuntimeProcessingEnvironmentSupplier#of()} will be used instead
    *
    * @param lock a {@link Lock} to use to serialize symbol completion; if {@code null} and {@code pe} is {@code null},
    * then a global {@link ReentrantLock} will be used instead; if {@code null} and {@code pe} is non-{@code null}, then
    * no serialization of symbol completion will occur <strong>and this {@link DefaultDomain} therefore will not be safe
    * for concurrent use by multiple threads</strong>
    *
-   * @see RuntimeProcessingEnvironmentSupplier
+   * @see RuntimeProcessingEnvironmentSupplier#get()
    *
-   * @see SymbolCompletionLock
+   * @see SymbolCompletionLock#INSTANCE
    */
   public DefaultDomain(final ProcessingEnvironment pe, final Lock lock) {
     super();
@@ -159,7 +161,7 @@ public List<? extends UniversalElement> allMembers(TypeElement e) {
       return UniversalElement.of(this.elements().getAllMembers(e), this);
     }
   }
-  
+
   /**
    * Returns a {@link UniversalType} representing an {@link javax.lang.model.type.ArrayType} whose {@linkplain
    * javax.lang.model.type.ArrayType#getComponentType() component type} {@linkplain #sameType(TypeMirror, TypeMirror) is
@@ -611,8 +613,10 @@ public UniversalType wildcardType(TypeMirror extendsBound, TypeMirror superBound
    */
 
 
+  // (Invoked only by method reference.)
   private static final void doNothing() {}
 
+  // (Invoked only by method reference.)
   private static final Unlockable noopLock() {
     return DefaultDomain::doNothing;
   }
@@ -626,7 +630,7 @@ private static final <E extends Element> E unwrap(final E e) {
   }
 
   private static final TypeMirror[] unwrap(final TypeMirror[] ts) {
-    if (ts == null || ts.length <= 0) {
+    if (ts == null || ts.length == 0) {
       return ts;
     }
     final TypeMirror[] rv = new TypeMirror[ts.length];

src/main/java/org/microbean/construct/Domain.java

@@ -66,10 +66,10 @@
 import static javax.lang.model.type.TypeKind.DECLARED;
 
 /**
- * A representation of a domain of valid Java constructs.
+ * A {@link PrimordialDomain} that represents a domain of valid Java language constructs.
  *
- * <p>A <dfn id="domain">domain</dfn> is a set of valid Java <a href="#construct">constructs</a>. A {@link Domain}
- * provides access to a domain and its members.</p>
+ * <p>A <dfn id="domain">domain</dfn> is a set of valid Java language <a href="#construct">constructs</a>. A {@link
+ * Domain} provides access to a domain and its members.</p>
  *
  * <p>A Java <dfn id="construct">construct</dfn> is either a <a href="#type">type</a> or an <a
  * href="#element">element</a>.</p>
@@ -91,6 +91,8 @@
  *
  * @see PrimordialDomain
  *
+ * @see DefaultDomain
+ *
  * @see <a href="https://bugs.openjdk.org/browse/JDK-8055219">JDK-8055219</a>
  */
 @SuppressWarnings("try")

src/main/java/org/microbean/construct/PrimordialDomain.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2025 microBean™.
+ * Copyright © 2025–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -42,6 +42,8 @@
  * @see #noType(TypeKind)
  *
  * @see #nullType()
+ *
+ * @see Domain
  */
 public interface PrimordialDomain {
 
@@ -95,7 +97,7 @@ public interface PrimordialDomain {
   /**
    * Returns a (non-{@code null}, determinate) {@link NullType} representing the null type.
    *
-   * <p>Implementations of thsi method must not return {@code null}.</p>
+   * <p>Implementations of this method must not return {@code null}.</p>
    *
    * @return a {@link NullType} representing the null type; never {@code null}
    *
@@ -110,9 +112,9 @@ public interface PrimordialDomain {
    * <p>The default implementation of this method may return {@code null} if the supplied {@code name} is {@code
    * null}.</p>
    *
-   * <p>In many implementations of domains, converting a {@link Name} to a {@link String} can cause problems if symbol
-   * completion is taking place concurrently and the symbol completion lock is not held. This method helps avoid those
-   * problems.</p>
+   * <p>In many implementations of {@link PrimordialDomain}s, converting a {@link Name} to a {@link String} can cause
+   * problems if symbol completion is taking place concurrently and the symbol completion lock is not held. This method
+   * helps avoid those problems.</p>
    *
    * <p>Overriding this method is not normally needed.</p>
    *
@@ -139,5 +141,5 @@ public default String toString(final CharSequence name) {
     default -> name.toString();
     };
   }
-  
+
 }

src/main/java/org/microbean/construct/Processor.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024–2025 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -204,6 +204,7 @@ public final boolean process(final Set<? extends TypeElement> annotations, final
     return false;
   }
 
+  // (Invoked only by method reference.)
   private static final void sink() {}
 
 }

src/main/java/org/microbean/construct/RuntimeProcessingEnvironmentSupplier.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024–2025 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -29,6 +29,9 @@
 /**
  * A utility class that can {@linkplain #of() supply} a {@link ProcessingEnvironment} suitable for use at runtime.
  *
+ * <p>Most users should simply {@linkplain DefaultDomain#DefaultDomain() use an appropriate <code>DefaultDomain</code>}
+ * instead of working directly with instances of this class.</p>
+ *
  * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
  *
  * @see #get()
@@ -39,7 +42,7 @@
  *
  * @see ProcessingEnvironment
  *
- * @see Domain
+ * @see DefaultDomain#DefaultDomain()
  */
 public final class RuntimeProcessingEnvironmentSupplier implements AutoCloseable, Supplier<ProcessingEnvironment> {
 
@@ -103,9 +106,12 @@ public final void close() {
    * <p><strong>{@link ProcessingEnvironment} instances are not guaranteed to be safe for concurrent use by multiple
    * threads.</strong></p>
    *
+   * <p>Most users should simply use an appropriate {@link DefaultDomain} instead of working directly with instances of
+   * this class.</p>
+   *
    * @return a non-{@code null} {@link ProcessingEnvironment}
    *
-   * @see Domain
+   * @see DefaultDomain#DefaultDomain()
    */
   @Override // Supplier<ProcessingEnvironment>
   public final ProcessingEnvironment get() {
@@ -139,11 +145,14 @@ private static final BlockingCompilationTask install(final Consumer<? super Bloc
   /**
    * Returns a non-{@code null} {@link RuntimeProcessingEnvironmentSupplier}.
    *
+   * <p>Most users should simply use an appropriate {@link DefaultDomain} instead of working directly with instances of
+   * this class.</p>
+   *
    * @return a non-{@code null} {@link RuntimeProcessingEnvironmentSupplier}
    *
    * @see ProcessingEnvironment
    *
-   * @see Domain
+   * @see DefaultDomain#DefaultDomain()
    */
   public static final RuntimeProcessingEnvironmentSupplier of() {
     return INSTANCE;

src/main/java/org/microbean/construct/SymbolCompletionLock.java

@@ -1,6 +1,6 @@
 /* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
  *
- * Copyright © 2024 microBean™.
+ * Copyright © 2024–2026 microBean™.
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
  * the License. You may obtain a copy of the License at
@@ -19,13 +19,18 @@
  * A class holding a {@link ReentrantLock} that should be used to serialize <dfn>symbol completion</dfn> and <dfn>name
  * expansion</dfn>.
  *
+ * <p>Most users should simply {@linkplain DefaultDomain#DefaultDomain() use an appropriate <code>DefaultDomain</code>}
+ * instead of working directly with instances of this class.</p>
+ *
  * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
  *
  * @see #INSTANCE
  *
  * @see Domain#lock()
  *
  * @see Domain#toString(CharSequence)
+ *
+ * @see DefaultDomain#DefaultDomain()
  */
 public final class SymbolCompletionLock {