fix(docs): adds javadocs for injection and extensions (#171)

container/test-spi/src/main/java/org/jboss/arquillian/container/test/spi/RemoteLoadableExtension.java

@@ -20,7 +20,10 @@
 import org.jboss.arquillian.core.spi.LoadableExtension;
 
 /**
- * RemoteLoadableExtension
+ * RemoteLoadableExtension.
+ * <p>
+ * This should be provided by a
+ * {@link org.jboss.arquillian.container.test.spi.client.deployment.AuxiliaryArchiveAppender}.
  *
  * @author <a href="mailto:aslak@redhat.com">Aslak Knutsen</a>
  * @version $Revision: $

core/api/src/main/java/org/jboss/arquillian/core/api/Instance.java

@@ -17,6 +17,11 @@
 package org.jboss.arquillian.core.api;
 
 /**
+ * An injectable instance.
+ * <p>
+ * All {@link org.jboss.arquillian.core.api.annotation.Inject} annotated fields must have this type or be a subtype
+ * of it.
+ * <p>
  * <pre>
  * {@code @Inject
  * private Instance<MyObject> myObjectInst;
@@ -28,6 +33,9 @@
  * }
  * }
  * </pre>
+ * <p>
+ * Instances are provided using the {@link InstanceProducer#set(Object)} method, they are not automatically detected or
+ * provided by Arquillian.
  *
  * @author <a href="mailto:aslak@redhat.com">Aslak Knutsen</a>
  * @version $Revision: $

core/api/src/main/java/org/jboss/arquillian/core/api/InstanceProducer.java

@@ -17,6 +17,18 @@
 package org.jboss.arquillian.core.api;
 
 /**
+ * An instance producer.
+ * <p>
+ * This is the only mechanism for providing instances to be injected.
+ * {@link org.jboss.arquillian.core.api.annotation.Inject} annotated instance producer fields must also declare a
+ * {@link org.jboss.arquillian.core.api.annotation.Scope} annotation, to indicate which context the instance will be
+ * produced for.
+ * <p>
+ * Typically, instances will be provided to the {@link #set(Object)} method during an appropriate lifecycle event.
+ * For example, application scoped instances may be set in an observer of the
+ * {@link org.jboss.arquillian.core.api.event.ManagerStarted} event. Remote loadable extensions for example may decide
+ * to register application scoped instances in an observer of the {@code BeforeSuite} event.
+ * <p>
  * <pre>
  * {@code @Inject @ApplicationScoped
  * private InstanceProducer<MyObject> myObjectInst;

core/api/src/main/java/org/jboss/arquillian/core/api/annotation/Inject.java

@@ -24,7 +24,22 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Inject
+ * Inject.
+ * <p>
+ * This can be used to inject instances managed by an Arquillian context.
+ * <p>
+ * Fields annotated with this must be of type {@link org.jboss.arquillian.core.api.Instance} or
+ * {@link org.jboss.arquillian.core.api.InstanceProducer}.
+ * <p>
+ * To provide an injected instance, it must be explicitly set on an injected
+ * {@link org.jboss.arquillian.core.api.InstanceProducer}, and that field must also have a {@link Scope} annotated context
+ * annotation on it, to indicate which context the instance is being produced for.
+ * <p>
+ * Note services provided by loadable extensions are not automatically available for injection. If an extension wishes to make
+ * a service injected, it must observe an appropriate lifecycle event, look the service up from the {@code ServiceLoader}, and
+ * provide the looked up service to a {@link org.jboss.arquillian.core.api.InstanceProducer} itself. Likewise, if an extension
+ * wishes to make any other component available for injection, it should provide it to an instance producer that in an
+ * appropriate lifecycle event observer.
  *
  * @author <a href="mailto:aslak@redhat.com">Aslak Knutsen</a>
  * @version $Revision: $

core/spi/src/main/java/org/jboss/arquillian/core/spi/LoadableExtension.java

@@ -20,22 +20,50 @@
 import org.jboss.arquillian.core.spi.context.Context;
 
 /**
- * LoadableExtension
+ * LoadableExtension.
+ * <p>
+ * Loadable extensions are loaded on the local side of Arquillan. For extensions, components, observers etc to run on
+ * the remote side, use {@code RemoteLoadableExtension} instead, and provide it via an
+ * {@code AuxilliaryArchiveAppender}.
  *
  * @author <a href="mailto:aslak@redhat.com">Aslak Knutsen</a>
  * @version $Revision: $
  */
 public interface LoadableExtension {
+    /**
+     * Implement to register any extensions.
+     */
     public void register(ExtensionBuilder builder);
 
     public interface ExtensionBuilder {
+        /**
+         * Register a service implementation.
+         * <p>
+         * The service can be looked up from the {@link ServiceLoader}. When instantiated, it will be injected
+         * according to any {@link org.jboss.arquillian.core.api.annotation.Inject} annotated
+         * {@link org.jboss.arquillian.core.api.Instance} fields.
+         * <p>
+         * Note that services are not automatically available for dependency injection, they must be provided
+         * explicitly to an {@link org.jboss.arquillian.core.api.InstanceProducer}.
+         */
         <T> ExtensionBuilder service(Class<T> service, Class<? extends T> impl);
 
+        /**
+         * Override a service.
+         */
         <T> ExtensionBuilder override(Class<T> service, Class<? extends T> oldServiceImpl,
             Class<? extends T> newServiceImpl);
 
+        /**
+         * Register an observer for events. This observer will be injected according to any
+         * {@link org.jboss.arquillian.core.api.annotation.Inject} annotated
+         * {@link org.jboss.arquillian.core.api.Instance} fields.
+         */
         ExtensionBuilder observer(Class<?> handler);
 
+        /**
+         * Register a context.
+         */
         ExtensionBuilder context(Class<? extends Context> context);
     }
 

core/spi/src/main/java/org/jboss/arquillian/core/spi/ServiceLoader.java

@@ -19,7 +19,24 @@
 import java.util.Collection;
 
 /**
- * ServiceLoader
+ * ServiceLoader.
+ * <p>
+ * This is the mechanism that can be used to load services registered by {@link LoadableExtension}'s. For example,
+ * to make a service available for dependency injection:
+ * <p>
+ * <pre>
+ * &#064;Inject
+ * private Instance&lt;ServiceLoader&gt; serviceLoader;
+ *
+ * &#064;Inject
+ * &#064;ApplicationScoped
+ * private InstanceProducer&lt;MyService&gt; myService;
+ *
+ * public void provideMyService(&#064;Observes ManagerStarted event) {
+ *     MyService service = serviceLoader.get().onlyOne(MyService.class, MyDefaultService.class);
+ *     myService.set(service);
+ * }
+ * </pre>
  *
  * @author <a href="mailto:aslak@conduct.no">Aslak Knutsen</a>
  * @version $Revision: $