Added default javax.inject comments to the Kotlin common components

src/commonMain/kotlin/com.chrynan.inject/Inject.kt

@@ -1,5 +1,160 @@
 package com.chrynan.inject
 
+/**
+ * Identifies injectable constructors, methods, and fields. May apply to static
+ * as well as instance members. An injectable member may have any access
+ * modifier (private, package-private, protected, public). Constructors are
+ * injected first, followed by fields, and then methods. Fields and methods
+ * in superclasses are injected before those in subclasses. Ordering of
+ * injection among fields and among methods in the same class is not specified.
+ *
+ * <p>Injectable constructors are annotated with {@code @Inject} and accept
+ * zero or more dependencies as arguments. {@code @Inject} can apply to at most
+ * one constructor per class.
+ *
+ * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
+ *       <i>ConstructorModifiers<sub>opt</sub></i>
+ *       <i>SimpleTypeName</i>(<i>FormalParameterList<sub>opt</sub></i>)
+ *       <i>Throws<sub>opt</sub></i>
+ *       <i>ConstructorBody</i></blockquote></tt>
+ *
+ * <p>{@code @Inject} is optional for public, no-argument constructors when no
+ * other constructors are present. This enables injectors to invoke default
+ * constructors.
+ *
+ * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">
+ *       {@literal @}Inject<sub><i>opt</i></sub>
+ *       <i>Annotations<sub>opt</sub></i>
+ *       public
+ *       <i>SimpleTypeName</i>()
+ *       <i>Throws<sub>opt</sub></i>
+ *       <i>ConstructorBody</i></blockquote></tt>
+ *
+ * <p>Injectable fields:
+ * <ul>
+ *   <li>are annotated with {@code @Inject}.
+ *   <li>are not final.
+ *   <li>may have any otherwise valid name.</li></ul>
+ *
+ * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
+ *       <i>FieldModifiers<sub>opt</sub></i>
+ *       <i>Type</i>
+ *       <i>VariableDeclarators</i>;</blockquote></tt>
+ *
+ * <p>Injectable methods:
+ * <ul>
+ *   <li>are annotated with {@code @Inject}.</li>
+ *   <li>are not abstract.</li>
+ *   <li>do not declare type parameters of their own.</li>
+ *   <li>may return a result</li>
+ *   <li>may have any otherwise valid name.</li>
+ *   <li>accept zero or more dependencies as arguments.</li></ul>
+ *
+ * <p><tt><blockquote style="padding-left: 2em; text-indent: -2em;">@Inject
+ *       <i>MethodModifiers<sub>opt</sub></i>
+ *       <i>ResultType</i>
+ *       <i>Identifier</i>(<i>FormalParameterList<sub>opt</sub></i>)
+ *       <i>Throws<sub>opt</sub></i>
+ *       <i>MethodBody</i></blockquote></tt>
+ *
+ * <p>The injector ignores the result of an injected method, but
+ * non-{@code void} return types are allowed to support use of the method in
+ * other contexts (builder-style method chaining, for example).
+ *
+ * <p>Examples:
+ *
+ * <pre>
+ *   public class Car {
+ *     // Injectable constructor
+ *     &#064;Inject public Car(Engine engine) { ... }
+ *
+ *     // Injectable field
+ *     &#064;Inject private Provider&lt;Seat> seatProvider;
+ *
+ *     // Injectable package-private method
+ *     &#064;Inject void install(Windshield windshield, Trunk trunk) { ... }
+ *   }</pre>
+ *
+ * <p>A method annotated with {@code @Inject} that overrides another method
+ * annotated with {@code @Inject} will only be injected once per injection
+ * request per instance. A method with <i>no</i> {@code @Inject} annotation
+ * that overrides a method annotated with {@code @Inject} will not be
+ * injected.
+ *
+ * <p>Injection of members annotated with {@code @Inject} is required. While an
+ * injectable member may use any accessibility modifier (including
+ * <tt>private</tt>), platform or injector limitations (like security
+ * restrictions or lack of reflection support) might preclude injection
+ * of non-public members.
+ *
+ * <h3>Qualifiers</h3>
+ *
+ * <p>A {@linkplain Qualifier qualifier} may annotate an injectable field
+ * or parameter and, combined with the type, identify the implementation to
+ * inject. Qualifiers are optional, and when used with {@code @Inject} in
+ * injector-independent classes, no more than one qualifier should annotate a
+ * single field or parameter. The qualifiers are bold in the following example:
+ *
+ * <pre>
+ *   public class Car {
+ *     &#064;Inject private <b>@Leather</b> Provider&lt;Seat> seatProvider;
+ *
+ *     &#064;Inject void install(<b>@Tinted</b> Windshield windshield,
+ *         <b>@Big</b> Trunk trunk) { ... }
+ *   }</pre>
+ *
+ * <p>If one injectable method overrides another, the overriding method's
+ * parameters do not automatically inherit qualifiers from the overridden
+ * method's parameters.
+ *
+ * <h3>Injectable Values</h3>
+ *
+ * <p>For a given type T and optional qualifier, an injector must be able to
+ * inject a user-specified class that:
+ *
+ * <ol type="a">
+ *   <li>is assignment compatible with T and</li>
+ *   <li>has an injectable constructor.</li>
+ * </ol>
+ *
+ * <p>For example, the user might use external configuration to pick an
+ * implementation of T. Beyond that, which values are injected depend upon the
+ * injector implementation and its configuration.
+ *
+ * <h3>Circular Dependencies</h3>
+ *
+ * <p>Detecting and resolving circular dependencies is left as an exercise for
+ * the injector implementation. Circular dependencies between two constructors
+ * is an obvious problem, but you can also have a circular dependency between
+ * injectable fields or methods:
+ *
+ * <pre>
+ *   class A {
+ *     &#064;Inject B b;
+ *   }
+ *   class B {
+ *     &#064;Inject A a;
+ *   }</pre>
+ *
+ * <p>When constructing an instance of {@code A}, a naive injector
+ * implementation might go into an infinite loop constructing an instance of
+ * {@code B} to set on {@code A}, a second instance of {@code A} to set on
+ * {@code B}, a second instance of {@code B} to set on the second instance of
+ * {@code A}, and so on.
+ *
+ * <p>A conservative injector might detect the circular dependency at build
+ * time and generate an error, at which point the programmer could break the
+ * circular dependency by injecting {@link Provider Provider&lt;A>} or {@code
+ * Provider<B>} instead of {@code A} or {@code B} respectively. Calling {@link
+ * Provider#get() get()} on the provider directly from the constructor or
+ * method it was injected into defeats the provider's ability to break up
+ * circular dependencies. In the case of method or field injection, scoping
+ * one of the dependencies (using {@linkplain Singleton singleton scope}, for
+ * example) may also enable a valid circular relationship.
+ *
+ * @see Qualifier @Qualifier
+ * @see Provider
+ */
 @Target(AnnotationTarget.FUNCTION, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY, AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 @MustBeDocumented

src/commonMain/kotlin/com.chrynan.inject/Named.kt

@@ -1,5 +1,17 @@
 package com.chrynan.inject
 
+/**
+ * String-based {@linkplain Qualifier qualifier}.
+ *
+ * <p>Example usage:
+ *
+ * <pre>
+ *   public class Car {
+ *     &#064;Inject <b>@Named("driver")</b> Seat driverSeat;
+ *     &#064;Inject <b>@Named("passenger")</b> Seat passengerSeat;
+ *     ...
+ *   }</pre>
+ */
 @Qualifier
 @MustBeDocumented
 @Retention(AnnotationRetention.RUNTIME)

src/commonMain/kotlin/com.chrynan.inject/Provider.kt

@@ -1,6 +1,41 @@
 package com.chrynan.inject
 
+/**
+ * Provides instances of {@code T}. Typically implemented by an injector. For
+ * any type {@code T} that can be injected, you can also inject
+ * {@code Provider<T>}. Compared to injecting {@code T} directly, injecting
+ * {@code Provider<T>} enables:
+ *
+ * <ul>
+ *   <li>retrieving multiple instances.</li>
+ *   <li>lazy or optional retrieval of an instance.</li>
+ *   <li>breaking circular dependencies.</li>
+ *   <li>abstracting scope so you can look up an instance in a smaller scope
+ *      from an instance in a containing scope.</li>
+ * </ul>
+ *
+ * <p>For example:
+ *
+ * <pre>
+ *   class Car {
+ *     &#064;Inject Car(Provider&lt;Seat> seatProvider) {
+ *       Seat driver = seatProvider.get();
+ *       Seat passenger = seatProvider.get();
+ *       ...
+ *     }
+ *   }</pre>
+ */
 expect interface Provider<T> {
 
+    /**
+     * Provides a fully-constructed and injected instance of {@code T}.
+     *
+     * @throws RuntimeException if the injector encounters an error while
+     *  providing an instance. For example, if an injectable member on
+     *  {@code T} throws an exception, the injector may wrap the exception
+     *  and throw it to the caller of {@code get()}. Callers should not try
+     *  to handle such exceptions as the behavior may vary across injector
+     *  implementations and even different configurations of the same injector.
+     */
     fun get(): T
 }

src/commonMain/kotlin/com.chrynan.inject/Qualifier.kt

@@ -1,5 +1,35 @@
 package com.chrynan.inject
 
+/**
+ * Identifies qualifier annotations. Anyone can define a new qualifier. A
+ * qualifier annotation:
+ *
+ * <ul>
+ *   <li>is annotated with {@code @Qualifier}, {@code @Retention(RUNTIME)},
+ *      and typically {@code @Documented}.</li>
+ *   <li>can have attributes.</li>
+ *   <li>may be part of the public API, much like the dependency type, but
+ *      unlike implementation types which needn't be part of the public
+ *      API.</li>
+ *   <li>may have restricted usage if annotated with {@code @Target}. While
+ *      this specification covers applying qualifiers to fields and
+ *      parameters only, some injector configurations might use qualifier
+ *      annotations in other places (on methods or classes for example).</li>
+ * </ul>
+ *
+ * <p>For example:
+ *
+ * <pre>
+ *   &#064;java.lang.annotation.Documented
+ *   &#064;java.lang.annotation.Retention(RUNTIME)
+ *   &#064;javax.inject.Qualifier
+ *   public @interface Leather {
+ *     Color color() default Color.TAN;
+ *     public enum Color { RED, BLACK, TAN }
+ *   }</pre>
+ *
+ * @see Named @Named
+ */
 @Target(AnnotationTarget.ANNOTATION_CLASS)
 @Retention(AnnotationRetention.RUNTIME)
 @MustBeDocumented

src/commonMain/kotlin/com.chrynan.inject/Scope.kt

@@ -1,5 +1,56 @@
 package com.chrynan.inject
 
+/**
+ * Identifies scope annotations. A scope annotation applies to a class
+ * containing an injectable constructor and governs how the injector reuses
+ * instances of the type. By default, if no scope annotation is present, the
+ * injector creates an instance (by injecting the type's constructor), uses
+ * the instance for one injection, and then forgets it. If a scope annotation
+ * is present, the injector may retain the instance for possible reuse in a
+ * later injection. If multiple threads can access a scoped instance, its
+ * implementation should be thread safe. The implementation of the scope
+ * itself is left up to the injector.
+ *
+ * <p>In the following example, the scope annotation {@code @Singleton} ensures
+ * that we only have one Log instance:
+ *
+ * <pre>
+ *   &#064;Singleton
+ *   class Log {
+ *     void log(String message) { ... }
+ *   }</pre>
+ *
+ * <p>The injector generates an error if it encounters more than one scope
+ * annotation on the same class or a scope annotation it doesn't support.
+ *
+ * <p>A scope annotation:
+ * <ul>
+ *   <li>is annotated with {@code @Scope}, {@code @Retention(RUNTIME)},
+ *      and typically {@code @Documented}.</li>
+ *   <li>should not have attributes.</li>
+ *   <li>is typically not {@code @Inherited}, so scoping is orthogonal to
+ *      implementation inheritance.</li>
+ *   <li>may have restricted usage if annotated with {@code @Target}. While
+ *      this specification covers applying scopes to classes only, some
+ *      injector configurations might use scope annotations
+ *      in other places (on factory method results for example).</li>
+ * </ul>
+ *
+ * <p>For example:
+ *
+ * <pre>
+ *   &#064;java.lang.annotation.Documented
+ *   &#064;java.lang.annotation.Retention(RUNTIME)
+ *   &#064;javax.inject.Scope
+ *   public @interface RequestScoped {}</pre>
+ *
+ * <p>Annotating scope annotations with {@code @Scope} helps the injector
+ * detect the case where a programmer used the scope annotation on a class but
+ * forgot to configure the scope in the injector. A conservative injector
+ * would generate an error rather than not apply a scope.
+ *
+ * @see Singleton @Singleton
+ */
 @Target(AnnotationTarget.ANNOTATION_CLASS)
 @Retention(AnnotationRetention.RUNTIME)
 @MustBeDocumented

src/commonMain/kotlin/com.chrynan.inject/Singleton.kt

@@ -1,5 +1,10 @@
 package com.chrynan.inject
 
+/**
+ * Identifies a type that the injector only instantiates once. Not inherited.
+ *
+ * @see Scope @Scope
+ */
 @Scope
 @MustBeDocumented
 @Retention(AnnotationRetention.RUNTIME)