Javadoc improvements

Author: rbygrave

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

@@ -4,6 +4,8 @@
 
 /**
  * A bean entry with priority and optional name.
+ *
+ * @see BeanScope#all()
  */
 public interface BeanEntry {
 

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

@@ -12,7 +12,7 @@
  *
  * <h3>Create a BeanScope</h3>
  * <p>
- * We can programmatically create a BeanScope via BeanScopeBuilder.
+ * We can programmatically create a BeanScope via {@code BeanScope.newBuilder()}.
  * </p>
  * <pre>{@code
  *
@@ -26,35 +26,75 @@
  *   }
  *
  * }</pre>
+ *
+ * <h3>External dependencies</h3>
+ * <p>
+ * We can supporting external dependencies when creating the BeanScope. We need to do 2 things.
+ * we need to specify these via
+ * </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)
+ *
+ * }</pre>
+ * <p>
+ * When we build the BeanScope provide the dependency via {@link BeanScopeBuilder#withBean(Class, Object)}.
+ *
+ * <pre>{@code
+ *
+ *   // provide external dependencies ...
+ *   Pump pump = ...
+ *
+ *   try (BeanScope scope = BeanScope.newBuilder()
+ *     .withBean(Pump.class, pump)
+ *     .build()) {
+ *
+ *     CoffeeMaker coffeeMaker = context.get(CoffeeMaker.class);
+ *     coffeeMaker.makeIt()
+ *   }
+ *
+ * }</pre>
  */
 public interface BeanScope extends AutoCloseable {
 
   /**
-   * Build a bean scope with options for shutdown hook and supplying test doubles.
+   * Build a bean scope with options for shutdown hook and supplying external dependencies.
    * <p>
-   * We would choose to use BeanScopeBuilder in test code (for component testing)
-   * as it gives us the ability to inject test doubles, mocks, spy's etc.
-   * </p>
+   * We can optionally:
+   * <ul>
+   *   <li>Provide external dependencies</li>
+   *   <li>Specify a parent BeanScope</li>
+   *   <li>Specify specific modules to wire</li>
+   *   <li>Specify to include a shutdown hook (to fire preDestroy lifecycle methods)</li>
+   *   <li>Use {@code forTesting()} to specify mocks and spies to use when wiring tests</li>
+   * </ul>
    *
    * <pre>{@code
    *
-   *   @Test
-   *   public void someComponentTest() {
-   *
-   *     MyRedisApi mockRedis = mock(MyRedisApi.class);
-   *     MyDbApi mockDatabase = mock(MyDbApi.class);
-   *
-   *     try (BeanScope scope = BeanScope.newBuilder()
-   *       .withBeans(mockRedis, mockDatabase)
-   *       .build()) {
+   *   // create a BeanScope ...
    *
-   *       // built with test doubles injected ...
-   *       CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
-   *       coffeeMaker.makeIt();
+   *   try (BeanScope scope = BeanScope.newBuilder()
+   *     .build()) {
    *
-   *       assertThat(...
-   *     }
+   *     CoffeeMaker coffeeMaker = context.get(CoffeeMaker.class);
+   *     coffeeMaker.makeIt()
    *   }
+   *
    * }</pre>
    */
   static BeanScopeBuilder newBuilder() {
@@ -102,10 +142,6 @@ static BeanScopeBuilder newBuilder() {
    *
    * }</pre>
    *
-   * <p>
-   * The classic use case for this is registering controllers or routes to
-   * web frameworks like Sparkjava, Javlin, Rapidoid etc.
-   *
    * @param annotation An annotation class.
    */
   List<Object> listByAnnotation(Class<?> annotation);
@@ -144,15 +180,14 @@ static BeanScopeBuilder newBuilder() {
   /**
    * Return all the bean entries from the scope.
    * <p>
-   * The bean entries include
-   * This includes entries from the parent scope if it has one.
+   * The bean entries include entries from the parent scope if it has one.
    *
    * @return All bean entries from the scope.
    */
   List<BeanEntry> all();
 
   /**
-   * Close the scope firing any <code>@PreDestroy</code> methods.
+   * Close the scope firing any <code>@PreDestroy</code> lifecycle methods.
    */
   void close();
 }

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

@@ -15,33 +15,33 @@
  *   // external dependencies
  *   Pump pump = ...
  *
- *   try (BeanScope scope = BeanScope.newBuilder()
+ *   BeanScope scope = BeanScope.newBuilder()
  *     .withBean(pump)
- *     .build()) {
+ *     .build();
+ *
+ *   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
+ *   coffeeMaker.makeIt();
  *
- *     CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
- *     coffeeMaker.makeIt();
- *   }
  * }</pre>
  */
 public interface BeanScopeBuilder {
 
   /**
    * Create the bean scope registering a shutdown hook (defaults to false, no shutdown hook).
    * <p>
-   * The expectation is that the BeanScopeBuilder is closed via code or via using
-   * try with resources.
+   * With {@code withShutdownHook(true)} a shutdown hook will be registered with the Runtime
+   * and executed when the JVM initiates a shutdown. This then will run the {@code preDestroy}
+   * lifecycle methods.
    * </p>
    * <pre>{@code
    *
    *   // automatically closed via try with resources
    *
-   *   try (BeanScope scope = BeanScope.newBuilder()
+   *   BeanScope scope = BeanScope.newBuilder()
    *     .withShutdownHook(true)
-   *     .build()) {
+   *     .build());
    *
-   *     String makeIt = scope.get(CoffeeMaker.class).makeIt();
-   *   }
+   *   // on JVM shutdown the preDestroy lifecycle methods are executed
    *
    * }</pre>
    *
@@ -59,15 +59,12 @@ public interface BeanScopeBuilder {
    *
    * <pre>{@code
    *
-   *   try (BeanScope scope = BeanScope.newBuilder()
+   *   BeanScope scope = BeanScope.newBuilder()
    *     .withModules(new CustomModule())
-   *     .build()) {
+   *     .build());
    *
-   *     // built with test doubles injected ...
-   *     CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
-   *     coffeeMaker.makeIt();
-   *
-   *   }
+   *   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
+   *   coffeeMaker.makeIt();
    *
    * }</pre>
    *
@@ -90,19 +87,12 @@ public interface BeanScopeBuilder {
    *   Pump pump = ...
    *   Grinder grinder = ...
    *
-   *   try (BeanScope scope = BeanScope.newBuilder()
+   *   BeanScope scope = BeanScope.newBuilder()
    *     .withBeans(pump, grinder)
-   *     .build()) {
+   *     .build();
    *
-   *     CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
-   *     coffeeMaker.makeIt();
-   *
-   *     Pump pump1 = scope.get(Pump.class);
-   *     Grinder grinder1 = scope.get(Grinder.class);
-   *
-   *     assertThat(pump1).isSameAs(pump);
-   *     assertThat(grinder1).isSameAs(grinder);
-   *   }
+   *   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
+   *   coffeeMaker.makeIt();
    *
    * }</pre>
    *
@@ -112,10 +102,7 @@ public interface BeanScopeBuilder {
   BeanScopeBuilder withBeans(Object... beans);
 
   /**
-   * Add a supplied bean instance with the given injection type.
-   * <p>
-   * This is typically a test double often created by Mockito or similar.
-   * </p>
+   * Add a supplied bean instance with the given injection type (typically an interface type).
    *
    * <pre>{@code
    *
@@ -168,7 +155,9 @@ public interface BeanScopeBuilder {
    * Build and return the bean scope.
    * <p>
    * The BeanScope is effectively immutable in that all components are created
-   * eagerly (eager singletons).
+   * and all PostConstruct lifecycle methods have been invoked.
+   * <p>
+   * The beanScope effectively contains eager singletons.
    *
    * @return The BeanScope
    */
@@ -187,10 +176,7 @@ interface ForTesting extends BeanScopeBuilder {
      *   try (BeanScope scope = BeanScope.newBuilder()
      *     .forTesting()
      *     .withMock(Pump.class)
-     *     .withMock(Grinder.class, grinder -> {
-     *       // setup the mock
-     *       when(grinder.grindBeans()).thenReturn("stub response");
-     *     })
+     *     .withMock(Grinder.class)
      *     .build()) {
      *
      *

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

@@ -2,7 +2,37 @@
 
 /**
  * Used to explicitly specify if it depends on externally provided beans or provides.
+ *
+ * <h3>External dependencies</h3>
  * <p>
+ * Use {@code requires} to specify dependencies that will be provided externally.
+ *
+ * <pre>{@code
+ *
+ *   // tell the annotation processor Pump and Grinder are provided externally
+ *   // otherwise it will think we have missing dependencies at compile time
+ *
+ *   @InjectModule(requires = {Pump.class, Grinder.class})
+ *
+ * }</pre>
+ *
+ * <h3>Custom scope depending on another scope</h3>
+ * <p>
+ * When using custom scopes we can have the case where we desire one scope to depend
+ * on another. In this case we put the custom scope annotation in requires.
+ * <p>
+ * For example lets say we have a custom scope called {@code StoreComponent} and that
+ * depends on {@code QueueComponent} custom scope.
+ *
+ * <pre>{@code
+ *
+ *   @Scope
+ *   @InjectModule(requires = {QueueComponent.class})
+ *   public @interface StoreComponent {
+ *   }
+ *
+ *
+ * }</pre>
  */
 public @interface InjectModule {
 
@@ -14,13 +44,19 @@
   /**
    * Explicitly define features that are provided by this module and required by other modules.
    * <p>
-   * This is used to order wiring across multiple modules.
+   * This is used to order wiring across multiple modules. Modules that provide dependencies
+   * should be wired before modules that require dependencies.
    */
   Class<?>[] provides() default {};
 
   /**
    * The dependencies that are provided externally or by other modules and that are required
    * when wiring this module.
+   * <p>
+   * This effectively tells the annotation processor that these types are expected to be
+   * provided and to not treat them as missing dependencies. If we don't do this the annotation
+   * processor thinks the dependency is missing and will error the compilation saying there is
+   * a missing dependency.
    */
   Class<?>[] requires() default {};
 

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

@@ -1,4 +1,24 @@
 /**
  * Avaje Inject API - see {@link io.avaje.inject.BeanScope}.
+ * <p>
+ * Create {@link io.avaje.inject.BeanScope} using a builder.
+ * Obtain beans from the scope and use them.
+ * <p>
+ * We should ensure the BeanScope is closed in order to fire
+ * preDestroy lifecycle methods. We can do this via a shutdown
+ * hook, or try with resource block or explicitly via application code.
+ *
+ * <pre>{@code
+ *
+ *   BeanScope scope = BeanScope.newBuilder()
+ *     .build();
+ *
+ *   CoffeeMaker coffeeMaker = scope.get(CoffeeMaker.class);
+ *   coffeeMaker.makeIt();
+ *
+ *   // fire preDestroy lifecycle methods
+ *   scope.close();
+ *
+ * }</pre>
  */
 package io.avaje.inject;