Update Javadocs

inject-aop/src/main/java/io/avaje/inject/aop/Invocation.java

@@ -5,7 +5,7 @@
 import java.util.function.Function;
 
 /**
- * Method invocation using in {@link MethodInterceptor#invoke(Invocation)} for Aspects.
+ * Method invocation used in {@link MethodInterceptor#invoke(Invocation)} for Aspects.
  * <p>
  * Represents a method invocation that can be intercepted with additional before and after
  * invocation logic.

inject-aop/src/main/java/io/avaje/inject/aop/InvocationException.java

@@ -1,7 +1,7 @@
 package io.avaje.inject.aop;
 
 /**
- * Exception occurring during method interception.
+ * Represents an exception occurring during method interception.
  * <p>
  * When using aspects and {@link MethodInterceptor} any throwable that is undeclared on the
  * method is caught and re-thrown as an InvocationException.

inject-aop/src/main/java/io/avaje/inject/aop/MethodInterceptor.java

@@ -4,19 +4,17 @@
 import java.lang.reflect.Method;
 
 /**
- * Provides method interception such that logic can be provided both before and after method invocation.
+ * Provides method interception logic that can be executed before, during, and after a method invocation.
  * <p>
  * MethodInterceptor instances are provided by {@link AspectProvider#interceptor(Method, Annotation)}.
  */
 @FunctionalInterface
 public interface MethodInterceptor {
 
   /**
-   * Implementation can perform before and after invocation logic.
+   * Intercepts the method invocation.
    * <p>
-   * If a method interceptor wants to replace the result it does this via {@link Invocation#result(Object)}.
-   * This is a little different to traditional method interceptors (i.e. <code>org.org.aopalliance.intercept.MethodInterceptor</code>).
-   * It is done this way to handle implied generic return types in the generated source code.
+   * If the interceptor wants to replace the result, it can be done via {@link Invocation#result(Object)}.
    *
    * @param invocation The invocation being intercepted
    * @throws Throwable If the interception or underlying invocation throws an exception

inject-aop/src/main/java/io/avaje/inject/aop/package-info.java

@@ -1,10 +1,9 @@
 /**
- * Support for AOP Aspects.
+ * Support for Aspect Oriented Programming.
  * <p>
- * Aspects allow us to define method interceptors and then have this method interception
- * apply to specific methods or all public methods of a class.
+ * Aspects allow us to define method interceptors and then apply to specific methods or all public methods of a class.
  * <p>
- * An example of an Aspect might be <em>Retry</em> which will invoke the underlying and
- * then retry potentially multiple times if that invocation fails.
+ * An example of an Aspect might be <em>@Retry</em> which will invoke the underlying method and
+ * then retry if that invocation fails.
  */
 package io.avaje.inject.aop;

inject/src/main/java/io/avaje/inject/AssistFactory.java

@@ -6,19 +6,17 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotate a bean for which we want avaje-inject to generate a factory.
+ * Annotate a bean for which we want to generate a factory.
  *
  * <p>The bean will have some properties of normal dependency injection components and others that
  * will be parameters to the method on the factory - these parameters are annotated with
  * {@code @Assisted}.
  *
  * <h3>Example</h3>
  *
- * <p>Create an interface which we want avaje-inject to generate an implementation. We desire this
- * because the factory has some managed dependencies that should be injected for us and some
- * dependencies that are provided by the application (and annotated with {@code Assisted}).
+ * <p>Create an interface for which to generate an implementation.
  *
- * <p>The factory supertype must be a functional interface, or an abstract class with only one
+ * <p>The factory interface must either be a functional interface, or an abstract class with only one
  * abstract method defined.
  *
  * <pre>{@code
@@ -29,9 +27,9 @@
  *
  * }</pre>
  *
- * <p>Create a bean annotated with {@code @AssistFactory} that specifies the factory. Any
- * dependencies that are annotated with {@code Assisted} will be parameters of the factory method,
- * the other dependencies will be managed and injected by avaje-inject.
+ * <p>Create a bean annotated with {@code @AssistFactory} that specifies the same factory interface. Any
+ * dependencies annotated with {@code Assisted} must be parameters of the factory method,
+ * the other dependencies will be managed and injected.
  *
  * <p>The {@code Assisted} parameters must match the factory method parameters by name and type. In
  * this example, {@code Path myPath} match in both CssScanner and in CssFactory.

inject/src/main/java/io/avaje/inject/Bean.java

@@ -55,13 +55,12 @@
    * Specify the priority of the destroy method to control its execution
    * order relative to other destroy methods.
    * <p>
-   * Low values execute earlier than high values. All destroy methods without
-   * any explicit priority are given a value of 1000.
+   * Low values execute earlier than high values.
    */
-  int destroyPriority() default 0;
+  int destroyPriority() default 1000;
 
   /**
-   * Specify that the concrete instance of the bean is an AutoCloseable. Use if your bean interface
+   * Specify that the concrete instance of the bean is an AutoCloseable. Use if the bean interface
    * doesn't extend AutoCloseable but the concrete class implements it.
    */
   boolean autoCloseable() default false;

inject/src/main/java/io/avaje/inject/BeanScope.java

@@ -33,33 +33,24 @@
  *
  * }</pre>
  *
- * <h3>External dependencies</h3>
+ * <h3>Runtime dependencies</h3>
  * <p>
- * We can supporting external dependencies when creating the BeanScope. We need to do 2 things.
- * we need to specify these via
+ * As the dependency graph is validated at compile-time, providing beans at runtime requires an extra step.
+ * To support external dependencies when creating the BeanScope, we can use the {@link io.avaje.inject.External @External} annotation.
  * </p>
- * <ul>
- *   <li>
- *       1. Specify the external dependency via {@code @InjectModule(requires=...)}.
- *       Otherwise at compile time the annotation processor detects it as a missing dependency and we can't compile.
- *   </li>
- *   <li>
- *       2. Provide the dependency when creating the BeanScope
- *   </li>
- * </ul>
  * <p>
  * For example, given we have Pump as an externally provided dependency.
  *
  * <pre>{@code
  *
- *   // tell the annotation processor Pump is provided externally
- *   // otherwise it thinks we have a missing dependency
- *
- *   @InjectModule(requires=Pump.class)
- *
+ *   class CoffeeMaker {
+ *     // tell the annotation processor Pump is provided externally at runtime
+ *     // otherwise it thinks we have a missing dependency
+ *     @External Pump pump;
+ *   }
  * }</pre>
  * <p>
- * When we build the BeanScope provide the dependency via {@link BeanScopeBuilder#bean(Class, Object)}.
+ * When building the BeanScope, the dependency must be provided manually via {@link BeanScopeBuilder#bean(Class, Object)}.
  *
  * <pre>{@code
  *

inject/src/main/java/io/avaje/inject/Component.java

@@ -50,7 +50,7 @@
 public @interface Component {
 
   /**
-   * Specify types to generate DI classes for. To avoid package splitting, the imported DI classes
+   * Specify types to generate DI classes for.
    *
    * <p>These types are typically in an external project / dependency or otherwise types that we
    * can't or don't want to explicitly annotate with {@code @Singleton}/{@code @Component}.

inject/src/main/java/io/avaje/inject/Factory.java

@@ -12,10 +12,9 @@
  * often use environment variables and system properties into account when building the bean.
  * </p>
  * <p>
- * Relative to <code>jakarta.inject.Provider</code> Factory and Bean provide a more flexible
+ * Relative to <code>jakarta.inject.Provider</code>, Factory and Bean provides a more flexible
  * approach that allows dependencies on the method (as method parameters) as well as multiple
- * methods on the single factory bean. The expectation is that we tend to use Factory and Bean
- * rather than Provider.
+ * methods on the single factory bean.
  * </p>
  *
  * <pre>{@code

inject/src/main/java/io/avaje/inject/InjectModule.java

@@ -9,7 +9,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Used to explicitly specify if it depends on externally provided beans or provides.
+ * Used to explicitly specify whether the current module depends on/provides beans or aspects.
  *
  * <h3>External dependencies</h3>
  * <p>

inject/src/main/java/io/avaje/inject/Lazy.java

@@ -6,10 +6,10 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks a Singleton, Component or Factory method beans to be initialised lazily.
+ * Marks a Singleton, Component or Factory method beans to be initialized lazily.
  * <p>
  * When annotating a {@link Factory} as {@code @Lazy} it means that the factory
- * itself is not lazy but all beans that it provides will have lazy initialisation.
+ * itself is not lazy but all beans that it provides will have lazy initialization.
  */
 @Retention(RetentionPolicy.SOURCE)
 @Target({ElementType.METHOD, ElementType.TYPE})

inject/src/main/java/io/avaje/inject/PostConstruct.java

@@ -20,13 +20,13 @@
  * The method on which the <code>PostConstruct</code> annotation is applied must fulfill
  * the following criteria:
  * <ul>
- * <li>The method must not have any parameters.</li>
+ * <li>The method must have a single {@link BeanScope} parameter or else have no parameters.</li>
  * <li>The method may be public, protected or package private.</li>
  * <li>The method must not be static.</li>
  * </ul>
  */
 @Documented
-@Retention(RUNTIME)
 @Target(METHOD)
+@Retention(RUNTIME)
 public @interface PostConstruct {
 }

inject/src/main/java/io/avaje/inject/Primary.java

@@ -6,7 +6,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Identify a bean as being the preferred bean to inject when multiple beans implement
+ * Identify a bean as the preferred bean to inject when multiple beans implement
  * the intended interface.
  *
  * <pre>{@code

inject/src/main/java/io/avaje/inject/QualifiedMap.java

@@ -8,7 +8,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks an <code>Map&lt;String, T&gt; </code> field/parameter to receive a map of beans keyed
+ * Marks an <code>Map&lt;String, T&gt;</code> field/parameter to receive a map of beans keyed
  * by qualifier name.
  *
  * <pre>{@code

inject/src/main/java/io/avaje/inject/spi/AvajeModule.java

@@ -3,7 +3,7 @@
 import java.lang.reflect.Type;
 
 /**
- * A AvajeModule that can be included in BeanScope.
+ * A Module containing dependencies that will be included in BeanScope.
  */
 public interface AvajeModule extends InjectExtension {
 

inject/src/main/java/io/avaje/inject/spi/ConfigPropertyPlugin.java

@@ -5,7 +5,7 @@
 import io.avaje.lang.NonNullApi;
 
 /**
- * InjectPlugin interface which contains the application properties used for wiring. Used with
+ * Plugin interface which contains the application properties used for wiring. Used with
  * {@link io.avaje.inject.RequiresProperty} and {@link io.avaje.inject.Profile}.
  *
  * <p>The plugin is loaded via ServiceLoader and defaults to an implementation that uses {@link

inject/src/main/java/io/avaje/inject/spi/DependencyMeta.java

@@ -6,7 +6,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Hold bean dependency metadata intended for internal use by code generation (Java annotation processing).
+ * Hold bean dependency metadata intended for internal use by the annotation processor.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.CLASS)

inject/src/main/java/io/avaje/inject/spi/GenericType.java

@@ -3,9 +3,9 @@
 import java.lang.reflect.Type;
 
 /**
- * Represents a full type including generics declaration, to avoid information loss due to type erasure.
+ * Represents a full type including generic declarations, to avoid information loss due to type erasure.
  * <p>
- * This is a cut down version of Helidon GenericType Apache 2 license.
+ * This is a cut down version of Helidon GenericType under the Apache 2 license.
  *
  * @param <T> the generic type parameter
  */

inject/src/main/java/io/avaje/inject/spi/GenericTypeUtil.java

@@ -8,7 +8,7 @@
 import java.util.Deque;
 
 /**
- * Cut down version of GenericTypeUtil from Helidon project Apache 2 license.
+ * Cut down version of GenericTypeUtil from Helidon project under the Apache 2 license.
  */
 final class GenericTypeUtil {
 

inject/src/main/java/io/avaje/inject/spi/InjectExtension.java

@@ -2,6 +2,20 @@
 
 import io.avaje.spi.Service;
 
-/** Superclass for all Inject SPI classes */
+/**
+ * Superclass for all Inject SPI classes
+ *
+ * <p>Add extensions by implementing one of the following extension interfaces and have it
+ * registered with the {@link java.util.ServiceLoader ServiceLoader} as an {@link InjectExtension}.
+ *
+ * <h4>Available Extensions</h4>
+ *
+ * <ul>
+ *   <li>{@link AvajeModule}
+ *   <li>{@link ConfigPropertyPlugin}
+ *   <li>{@link InjectPlugin}
+ *   <li>{@link ModuleOrdering}
+ * </ul>
+ */
 @Service
 public interface InjectExtension {}

inject/src/main/java/io/avaje/inject/spi/ModuleOrdering.java

@@ -4,7 +4,7 @@
 import java.util.Set;
 
 /**
- * Determines Wiring order.
+ * Determines Multi-Module wiring order.
  */
 public interface ModuleOrdering extends InjectExtension {