improvements to the documentation.

[utils] / support / inject / src / main / java / org / wamblee / inject / package-info.java

diff --git a/support/inject/src/main/java/org/wamblee/inject/package-info.java b/support/inject/src/main/java/org/wamblee/inject/package-info.java
index 3cc9841efa66b9496980dd78cf18cd34f4051f12..c07c8ab89a81d11168956f4f36b7c956eeddf534 100644 (file)
--- a/support/inject/src/main/java/org/wamblee/inject/package-info.java
+++ b/support/inject/src/main/java/org/wamblee/inject/package-info.java
@@ -14,28 +14,37 @@
  * limitations under the License.
  */
 /**
- * This package provides a simple general framework for dependency injection. 
+ * This package provides a mini-framework for interfacing to existing dependency injection 
+ * mechanisms. This package does not provide dependency injection, but implementations are expected to 
+ * implement it, usually by delegating to an existing dependency injection framework. The interfaces in this
+ * package provide independence on the actual framework chosen and also allow for better testability. 
+ * 
+ * <h2>Users of the package</h2>
+ * 
+ * <p>Users of this package will typically use: </p>
+ * <ul>
+ *   <li> <code>SimpleInjector</code>: This is the class used to perform injection of dependencies into 
+ *        a given object. </li>
+ *   <li> <code>Injectable</code>: By subclassing this class, the classes automatically get their 
+ *        dependencies injected at construction. </li>
+ *   <li> <code>InjectorFactoryBuilder</code>: To get an injector factory reference for use in the 
+ *       <code>SimpleInjector</code>
+ * </ul>
+ * 
+ * <h2>Implementors of the package</h2>
+ * 
+ * <p>Of interest to implementations of this package integrating with dependency injection frameworks are: </p>
  * <ul>
- *   <li> <code>Injector</code>: The main interface is the {@link Injector}, by which injection is done.</li>
+ *   <li> <code>Injector</code>: The main interface to be implemented is the {@link Injector}, by which injection is done.</li>
  *   <li> <code>InjectorFactory</code>: Injectors are created by an implementation of the {@link InjectorFactory} which 
  * creates injectors based on the class.</li>
- *   <li> <code>InjectorFactoryBuilder</code>: To obtain an <code>InjectorFactory</code>, 
- * either create one explicitly, or use {@link InjectorFactoryBuilder} to obtain 
- * one automatically (preferred). The last method uses {@link java.util.ServiceLoader}
- * to find the injectorfactory to use. 
+ *   <li> <code>InjectorFactoryBuilder</code>: Implementations must make their <code>InjectorFactory</code>
+ *       available through the <code>ServiceLoader</code> mechanism. 
  *   </li>
  * </ul>
  * 
+ * <p>Class overview</p>
  * <img src="doc-files/Class_Diagram__overview.png"/>
- * <p>
- * Note that this package does not contain implementations of the injectors. For that, a separate 
- * package must be used (e.g. for Contexts and Dependency Injection). 
- * </p>
- * 
- * <p>
- * Implementations of this package must provide an implementation of the {@link InjectorFactory} and
- * must make this implementation discoverable through the {@link java.util.ServiceLoader} mechanism. 
- * </p>
  *
  */
 package org.wamblee.inject;