deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rafab...@apache.org
Subject [2/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of javadoc: core/api
Date Tue, 11 Nov 2014 19:36:27 GMT
http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
index 1e2cc0a..06a3e53 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exclude/Exclude.java
@@ -36,64 +36,73 @@ import java.lang.annotation.Target;
  * @Exclude(onExpression="[my custom expression syntax]", interpretedBy=CustomExpressionInterpreter.class)
  * </pre>
  *
- * <p/>
- * examples:
- * <p/>
- * <p>the following bean gets excluded in any case</p>
+ * <b>Examples:</b>
+ * <br/>
+ * <ul>
+ * <li>
+ * The following bean gets excluded in any case
  * <pre>
  * &#064;Exclude
  * public class NoBean {}
  * </pre>
+ * </li>
  *
- * <p/>
- * <p>the following bean gets excluded in case of project-stage development</p>
+ * <li>
+ * The following bean gets excluded when the ProjectStage is 'Development'
  * <pre>
  * &#064;Exclude(ifProjectStage = ProjectStage.Development.class)
  * public class ProductionBean {}
  * </pre>
+ * </li>
  *
- * <p/>
- * <p>the following bean gets excluded in every case except of project-stage development</p>
+ * <li>
+ * The following bean gets excluded in every case except when then ProjectStage is 'Development'
  * <pre>
  * &#064;Exclude(exceptIfProjectStage = ProjectStage.Development.class)
  * public class DevBean {}
  * </pre>
+ * </li>
  *
- * <p/>
- * <p>the following bean gets excluded if the expression evaluates to true.
- * that means there is a configured property called 'myProper' with the value 'myValue'</p>
+ * <li>
+ * The following bean gets excluded if the expression evaluates to true, which means there is a configured property
+ * called 'myProperty' with the value 'myValue'
  * <pre>
  * &#064;Exclude(onExpression="myProperty==myValue")
  * public class ProductionBean {}
  * </pre>
+ * </li>
  *
- * <p/>
- * <p>the following bean gets excluded if the expression evaluates to true</p>
+ * <li>The following bean gets excluded if the expression evaluates to true
+ * <pre>
  * &#064;Exclude(onExpression="[my custom expression syntax]", interpretedBy=CustomExpressionInterpreter.class)
  * public class ProductionBean {}
+ * </pre>
+ * </li>
+ * </ul>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.TYPE })
 public @interface Exclude
 {
     /**
-     * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s
-     * which lead to deactivating this bean.
-     * If the current ProjectStage is in this list, the bean will get vetoed.
+     * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s which lead to deactivating this bean. If
+     * the current ProjectStage is in this list, the bean will get vetoed.
+     *
      * @return 1-n project-stages which are not allowed for the annotated artifact
      */
     Class<? extends ProjectStage>[] ifProjectStage() default { };
 
     /**
-     * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s
-     * which lead to activating this bean.
-     * If the current ProjectStage is not in this list, the bean will get vetoed.
+     * The {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}s which lead to activating this bean. If the
+     * current ProjectStage is not in this list, the bean will get vetoed.
+     *
      * @return 1-n project-stages which are allowed for the annotated artifact
      */
     Class<? extends ProjectStage>[] exceptIfProjectStage() default { };
 
     /**
-     * Expression which signals if the annotated bean should be deactivated or not
+     * Expression which signals if the annotated bean should be deactivated or not.
+     *
      * @return expression-string which will be interpreted
      */
     String onExpression() default "";

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
index 4c6935e..b102c1b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/BasePropertyExpressionInterpreter.java
@@ -19,7 +19,7 @@
 package org.apache.deltaspike.core.api.interpreter;
 
 /**
- * Base implementation for simple (property) expressions
+ * Base implementation for simple (property) expressions.
  *
  * Supported operations:<p/>
  * <ul>

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
index a86bb6a..c19e26b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/ExpressionInterpreter.java
@@ -19,14 +19,19 @@
 package org.apache.deltaspike.core.api.interpreter;
 
 /**
- * Interface for interpreting an expression e.g. provided by
- * {@link org.apache.deltaspike.core.api.exclude.Exclude#onExpression()}
+ * Generic interface for evaluation of expressions, like the ones provided by
+ * {@link org.apache.deltaspike.core.api.exclude.Exclude#onExpression()}.
+ * 
+ * @param <E> expression type
+ * @param <R> result type
  */
 public interface ExpressionInterpreter<E, R>
 {
     /**
-     * Evaluates the given expression and returns the result for it
-     * @param expression expression which should be evaluated
+     * Evaluates the given expression and returns the result for it.
+     *
+     * @param expression expression to evaluate
+     *
      * @return result of the evaluated expression
      */
     R evaluate(E expression);

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
index 29634d7..cceb2f1 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/interpreter/SimpleOperationEnum.java
@@ -19,7 +19,7 @@
 package org.apache.deltaspike.core.api.interpreter;
 
 /**
- * Operations supported by {@link BasePropertyExpressionInterpreter}
+ * Operations supported by {@link BasePropertyExpressionInterpreter}.
  */
 enum SimpleOperationEnum
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
index 31c2aa6..d510d40 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxBroadcaster.java
@@ -21,9 +21,8 @@ package org.apache.deltaspike.core.api.jmx;
 import javax.management.Notification;
 
 /**
- * Interface used to send JMX message from "CDI MBeans".
- * It can only be used from CDI MBeans and should get injected
- * in other beans.
+ * Interface used to send JMX message from "CDI MBeans". It can only be used from CDI MBeans and should get injected in
+ * other beans.
  */
 public interface JmxBroadcaster
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
index 82a79aa..1b1001b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/JmxManaged.java
@@ -27,12 +27,12 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This annotation can be used either on a field or a method.
+ * Describes a JMX operation or attribute, when used on a method or a field, respectively.
  *
  * Used on a method it describes a JMX operation with an optional description.
  *
- * Used on a field it describes a JMX attribute. This attribute is readable
- * if a getter on this field is available and writable is a setter is found.
+ * Used on a field it describes a JMX attribute. This attribute is readable if a getter on this field is available and
+ * writable if a setter is found.
  */
 @Retention(RUNTIME)
 @Target({ FIELD, METHOD })

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
index f96de28..0120ec8 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/jmx/MBean.java
@@ -34,17 +34,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface MBean
 {
     /**
-     * @return the category to use if no objectName was specified. Default is "org.apache.deltaspike"
-     * and can be overriden either directly by the value or by a key used to resolve a value using
-     * {@see org.apache.deltaspike.core.api.config.ConfigResolver}. It is a key if the value is
-     * between bracket. Default key is "org.apache.deltaspike.mbean.category".
+     * @return the category to use if no objectName was specified. Default is "org.apache.deltaspike" and can be
+     *         overriden either directly by the value or by a key used to resolve a value using
+     *         {@link org.apache.deltaspike.core.api.config.ConfigResolver}. It is a key if the value is between
+     *         brackets. Default key is "org.apache.deltaspike.mbean.category".
      */
     String category() default "{org.apache.deltaspike.mbean.category}";
 
     /**
-     * @return the name of the bean used if no objectName was specified.
-     * It is used with category value to create the MBean {@see javax.management.ObjectName}
-     * using the following pattern: &lt;category&gt;:type=MBeans,name=&lt;name&gt;
+     * @return the name of the bean used if no objectName was specified. It is used with category value to create the
+     *         MBean {@link javax.management.ObjectName} using the following pattern:
+     *         &lt;category&gt;:type=MBeans,name=&lt;name&gt;
      */
     String name() default "";
 

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
index 21609ed..e2e6aec 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/LocaleResolver.java
@@ -25,12 +25,13 @@ import java.util.Locale;
 import org.apache.deltaspike.core.api.config.DeltaSpikeConfig;
 
 /**
- * <p>Provides the current {@link java.util.Locale}.</p>
- * <p>DeltaSpike provides a default implementation which
- * returns the current system Locale.</p>
- * <p>An application can provide an own implementation as
- * &#064;Alternative. This could e.g. examine a JSF View or the Locale
- * of any currently logged in User.</p>
+ * Provides the current {@link java.util.Locale}.
+ *
+ * <p>
+ * DeltaSpike provides a default implementation which returns the current system Locale.</p>
+ * <p>
+ * An application can provide custom implementation as an &#064;Alternative. This could e.g. examine a JSF View or the
+ * Locale of any currently logged in User.</p>
  */
 public interface LocaleResolver extends Serializable, DeltaSpikeConfig
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
index 5184cb1..2e97d68 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/Message.java
@@ -22,46 +22,48 @@ import java.io.Serializable;
 import java.util.Collection;
 
 /**
- * <p>Basic interface for all messages.</p>
+ * Basic interface for all messages.
  *
- * <p>A <code>Message</code> is not a simple String but all the
- * information needed to create those Strings for multiple situations.
- * The situation ist determined by the used {@link MessageContext}.</p>
+ * <p>
+ * A <code>Message</code> is not a simple String but all the information needed to create those Strings for multiple
+ * situations. The situation is determined by the used {@link MessageContext}.</p>
  */
 public interface Message extends Serializable
 {
     /**
-     * @param messageTemplate message key (or inline-text) for the current message
-     * @return the current instance of the message builder to allow a fluent api
+     * @param messageTemplate message key (or plain text) for the current message
+     *
+     * @return the current instance of the message builder to allow a fluent API
      */
     Message template(String messageTemplate);
 
     /**
      * @param arguments numbered and/or named argument(s) for the current message
-     * @return the current instance of the message builder to allow a fluent api
+     *
+     * @return the current instance of the message builder to allow a fluent API
      */
     Message argument(Serializable... arguments);
     
     /**
-     * Argument array.  Similar to argument except it is meant to handle an array being passed in via a chain.
-     * 
-     * @param arguments
-     *            the arguments
+     * Argument array. Similar to argument except it is meant to handle an array being passed in via a chain.
+     *
+     * @param arguments the arguments
+     *
      * @return the message
      */
     Message argumentArray(Serializable[] arguments);
     
     /**
-     * Argument.  Similar to the other argument methods, exception it handles collections.
-     * 
-     * @param arguments
-     *            the arguments
+     * Argument. Similar to the other argument methods, this one handles collections.
+     *
+     * @param arguments the arguments
+     *
      * @return the message
      */
     Message argument(Collection<Serializable> arguments);
 
     /**
-     * @return the message key (or inline-text) of the current message
+     * @return the message key (or plain text) of the current message
      */
     String getTemplate();
 
@@ -71,38 +73,28 @@ public interface Message extends Serializable
     Object[] getArguments();
 
     /**
-     * Renders the Message to a String, using the {@link MessageContext}
-     * which created the Message.
+     * Renders the Message to a String, using the {@link MessageContext} which created the Message.
      */
     String toString();
 
     /**
-     * Renders the Message to a String, using an
-     * arbitrary {@link MessageContext}.
+     * Renders the Message to a String, using an arbitrary {@link MessageContext}.
      */
     String toString(MessageContext messageContext);
 
     /**
-     * Renders the Message to a String, using the {@link MessageContext}
-     * which created the Message.
-     * While resolving the message we will
-     * first search for a messageTemplate with the given category by
-     * just adding a dot '_' and the category String to the
-     * {@link #getTemplate()}.
-     * If no such a template exists we will fallback to the version
-     * without the category String
+     * Renders the Message to a String, using the {@link MessageContext} which created the Message. While resolving the
+     * message we will first search for a messageTemplate with the given category by just adding an underscore '_' and
+     * the category String to the {@link #getTemplate()}. If no such template exists we will fall back to the version
+     * without the category String.
      */
     String toString(String category);
 
     /**
-     * Renders the Message to a String, using an
-     * arbitrary {@link MessageContext}.
-     * While resolving the message we will
-     * first search for a messageTemplate with the given category by
-     * just adding a dot '_' and the category String to the
-     * {@link #getTemplate()}.
-     * If no such a template exists we will fallback to the version
-     * without the category String
+     * Renders the Message to a String, using an arbitrary {@link MessageContext}. While resolving the message we will
+     * first search for a messageTemplate with the given category by just adding an underscore '_' and the category
+     * String to the {@link #getTemplate()}. If no such template exists we will fall back to the version without the
+     * category String.
      */
     String toString(MessageContext messageContext, String category);
 

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
index 4804dd8..399a6c6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageBundle.java
@@ -26,42 +26,42 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * <p>Marker annotation for a message-bundle interface which provides type-safe messages.</p>
+ * Marker annotation for a message-bundle interface which provides type-safe messages.
  *
- * <p>This annotation must only be used on interfaces.
- * If this annotation gets used on a concrete class, a deployment error results!</p>
+ * <p>
+ * This annotation must only be used on interfaces. If this annotation gets used on a concrete class, a deployment error
+ * results!</p>
  *
  * <h3>Type-safe Messages</h3>
- * <p>Each method on an interface annotated with <code>&#064;MessageBundle</code>
- * will form a type-safe message. The message lookup key
- * (resource bundle key) can either be defined by annotating those methods
- * with &#064;{@link MessageTemplate}) or by convention. if no &#064;{@link MessageTemplate}
- * annotation is used on a method, the case sensitive method-name name
- * will be used as resource key.</p>
+ * <p>
+ * Each method on an interface annotated with <code>&#064;MessageBundle</code> will form a type-safe message. The
+ * message lookup key (resource bundle key) can either be defined by annotating those methods with
+ * &#064;{@link MessageTemplate}) or by convention. if no &#064;{@link MessageTemplate} annotation is used on a method,
+ * the case sensitive method name name will be used as resource key.</p>
  *
  * <h3>Message Parameters</h3>
- * <p>The parameters of the declared methods will be automatically passed
- * as message parameters to the {@link org.apache.deltaspike.core.api.message.MessageResolver}.
- * Please note that all passed parameters should be {@link java.io.Serializable}.
- * If a parameter is not Serializable, we will instead store the <code>toString()</code>
+ * <p>
+ * The parameters of the declared methods will be automatically passed as message parameters to the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver}. Please note that all passed parameters should be
+ * {@link java.io.Serializable}. If a parameter is not Serializable, we will instead store the <code>toString()</code>
  * of the passed parameter.</p>
  *
  *
  * <h3>Message Sources</h3>
- * <p>The {@link java.util.ResourceBundle} or other resource lookup source which might be used is
- * determined by the {@link org.apache.deltaspike.core.api.message.MessageResolver}
- * in conjunction with
- * {@link org.apache.deltaspike.core.api.message.MessageContext#messageSource(String...)}.
- * The fully qualified class name of the interface annotated with
- * &#064;MessageBundle will automatically be registered as additional
+ * <p>
+ * The {@link java.util.ResourceBundle} or other resource lookup source which might be used is determined by the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver} in conjunction with
+ * {@link org.apache.deltaspike.core.api.message.MessageContext#messageSource(String...)}. The fully qualified class
+ * name of the interface annotated with &#064;MessageBundle will automatically be registered as additional
  * <code>messageSource</code> for those messages.</p>
  *
+ * <p>
+ * <code>&#064;MessageBundle</code> can be combined with {@link MessageContextConfig} to further customize the
+ * message resolution and processing.</p>
  *
- * <p><code>&#064;MessageBundle</code> can be combined with {@link MessageContextConfig}
- * to further customize the message-resolution and processing process.</p>
- *
- * <p>Debug hint: Set a breakpoint in <code>MessageBundleInvocationHandler#invoke</code>.
- * This will get called for every message bundle invocation.</p>
+ * <p>
+ * Debug hint: Set a breakpoint in <code>MessageBundleInvocationHandler#invoke</code>. This will get called for every
+ * message bundle invocation.</p>
  */
 @Target({ TYPE })
 @Retention(RUNTIME)

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
index e765b10..17bb699 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContext.java
@@ -23,24 +23,27 @@ import java.util.List;
 
 /**
  * Central context for handling dynamic messages.
- * Instances of this type are mutable but also {@link Cloneable}.
- * If you need a new instance, then use {@link Object#clone()}
+ * <br/>
+ * Instances of this type are mutable but also {@link Cloneable}. If you need a new instance, then use
+ * {@link Object#clone()}.
  */
 public interface MessageContext extends LocaleResolver, Serializable, Cloneable
 {
     /**
-     * Clones the current MessageContext
+     * Clones the current MessageContext.
      */
     MessageContext clone();
 
     /**
-     * @return message based on the current context modifiable via a fluent api
+     * @return a message based on the current context modifiable via a fluent API
      */
     Message message();
 
     /**
-     * Allows to add a message-source instance which can be used by a {@link MessageResolver}
-     * @param messageSource message-source to add
+     * Configures a message source instance for use by a {@link MessageResolver}.
+     *
+     * @param messageSource message source to add
+     *
      * @return the instance of the current message context builder
      */
     MessageContext messageSource(String... messageSource);
@@ -79,7 +82,7 @@ public interface MessageContext extends LocaleResolver, Serializable, Cloneable
     LocaleResolver getLocaleResolver();
 
     /**
-     * @return list of registered message-sources
+     * @return list of registered message sources
      */
     List<String> getMessageSources();
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
index 260bd72..b2a2d43 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageContextConfig.java
@@ -26,8 +26,7 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Allows to customize the message-resolution and processing
- * in combination with {@link MessageBundle}.
+ * Configures message resolution and processing of a {@link MessageBundle}.
  */
 @Target({ TYPE })
 @Retention(RUNTIME)
@@ -35,39 +34,42 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface MessageContextConfig
 {
     /**
-     * <p>Additional message-source.</p>
+     * <p>Additional message source.</p>
      *
-     * <p>A message-source is a lookup hint for the {@link MessageResolver}.
-     * For the default MessageResolver this is the name of the
-     * {@link java.util.ResourceBundle}.</p>
+     * <p>A message source is a lookup hint for the {@link MessageResolver}. For the default MessageResolver this is the
+     * name of the {@link java.util.ResourceBundle}.</p>
      *
-     * <p>Example: For using 2 additional ResourceBundles for the lookup,
-     * you can use the MessageContextConfig like that:
+     * <p>Example: To use 2 additional ResourceBundles for the lookup, you can configure the MessageContextConfig like
+     * this:
      * <pre>
      *  &#064;MessageBundle
      *  &#064;MessageContextConfig(messageSource = {"mycomp.ErrorMessages","mycomp.BusinessMessages"})
      *  public interface MyCompanyMessages {...
-     * </pre>.</p>
+     * </pre>.
+     * </p>
+     *
      * @return classes of the message-sources
      */
     String[] messageSource() default { };
 
     /**
-     * {@link MessageResolver} which should be used for resolving the message-template (= basic text)
-     * @return class of the {@link MessageResolver}-bean or the default marker
+     * {@link MessageResolver} to use for resolution of message templates to message text.
+     *
+     * @return class of the {@link MessageResolver} bean or the default marker
      */
     Class<? extends MessageResolver> messageResolver() default MessageResolver.class;
 
     /**
-     * {@link MessageInterpolator} which should be used for replacing the placeholders in the resolved text
-     * @return class of the {@link MessageInterpolator}-bean or the default marker
+     * {@link MessageInterpolator} to use for interpolation of placeholders in the resolved text.
+     *
+     * @return class of the {@link MessageInterpolator} bean or the default marker
      */
     Class<? extends MessageInterpolator> messageInterpolator() default MessageInterpolator.class;
 
     /**
-     * {@link LocaleResolver} which should be used for providing the locale for resolving
-     * the message-template (= basic text)
-     * @return class of the {@link LocaleResolver}-bean or the default marker
+     * {@link LocaleResolver} providing the locale for message template resolution.
+     *
+     * @return class of the {@link LocaleResolver} bean or the default marker
      */
     Class<? extends LocaleResolver> localeResolver() default LocaleResolver.class;
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
index 13d2d86..e0f3466 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageInterpolator.java
@@ -24,28 +24,26 @@ import java.util.Locale;
 import org.apache.deltaspike.core.api.config.DeltaSpikeConfig;
 
 /**
- * <p>Implementations are responsible to replace placeholders
- * in a message with the final value.</p>
+ * Implementations are responsible to replace placeholders in a message with the final value.
  *
- * <p>An application can provide an own implementation as
- * &#064;Alternative.</p>
+ * <p>
+ * An application can provide a custom implementation as &#064;Alternative.</p>
  *
- * <p>A simple implementation which uses the
- * {@link String#format(java.util.Locale, String, Object...)}
- * will be used by default.</p>
+ * <p>
+ * A simple implementation which uses the {@link String#format(java.util.Locale, String, Object...)} will be used by
+ * default.</p>
  */
 public interface MessageInterpolator extends Serializable, DeltaSpikeConfig
 {
     /**
-     * replaces the arguments of the given message with the given arguments
+     * Replaces the arguments of the given message with the given arguments.
      *
-     * instead of a MessageContextAware interface. we need it to avoid expensive operations like locking or deep cloning
      * @param messageText the message text which has to be interpolated
-     * @param arguments a list of numbered and/or named arguments for the current message
-     * @param locale to use for the formatting
-     * @return the final (interpolated) message text
-     *         if it was possible to replace the parameters with the given arguments
-     *         the unmodified messageText otherwise
+     * @param arguments   a list of numbered and/or named arguments for the current message
+     * @param locale      to use for the formatting
+     *
+     * @return the final (interpolated) message text if it was possible to replace the parameters with the given
+     *         arguments, or the unmodified messageText otherwise
      */
     String interpolate(String messageText, Serializable[] arguments, Locale locale);
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
index f269e50..6fb71ee 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageResolver.java
@@ -21,7 +21,7 @@ package org.apache.deltaspike.core.api.message;
 import java.io.Serializable;
 
 /**
- * Implementations have to resolve the text stored for a given key in the message-source they are aware of.
+ * Implementations have to resolve the text stored for a given key in the message source they are aware of.
  * Implementations should always be &#064;Dependent scoped!
  */
 public interface MessageResolver extends Serializable
@@ -30,11 +30,12 @@ public interface MessageResolver extends Serializable
 
     /**
      *
-     * @param messageContext messageContext which should be used
-     * @param messageTemplate the message key (or in-lined text) of the current message
-     * @param category the sub-category of the message, e.g. 'longText'. Can be <code>null</code>
-     * @return the final but not interpolated message text
-     *         or <code>null</code> if an error happened or the resource could not be resolved.
+     * @param messageContext  messageContext which should be used
+     * @param messageTemplate the message key (or inline text) of the current message
+     * @param category        the category of the message, e.g. 'longText'. Can be <code>null</code>
+     *
+     * @return the final but not interpolated message text or <code>null</code> if an error happened or the resource
+     *         could not be resolved.
      */
     String getMessage(MessageContext messageContext, String messageTemplate, String category);
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
index d6f1c3f..09d5764 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/message/MessageTemplate.java
@@ -26,29 +26,26 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * <p>Provides the message(-template) for type-safe messages.</p>
+ * Provides the message (template) for type-safe messages.
  *
- * <p>This only works on interfaces which are annotated with
- * {@link MessageBundle}.</p>
+ * <p>
+ * This only works on interfaces which are annotated with {@link MessageBundle}.</p>
  *
- * <p>Depending on the {@link org.apache.deltaspike.core.api.message.MessageResolver}
- * this message-template value might be used as key to lookup internationalized values
- * from a {@link java.util.ResourceBundle}.</p>
+ * <p>
+ * Depending on the {@link org.apache.deltaspike.core.api.message.MessageResolver} this message template value might be
+ * used as key to lookup internationalized values from a {@link java.util.ResourceBundle}.</p>
  *
- * <p>A MessageTemplate value which starts and ends with bracelets '{', '}' will
- * be interpreted as key for resolving from a ResourceBundle or any other lookup mechanism
- * determined by the {@link org.apache.deltaspike.core.api.message.MessageResolver}.
- * A small example:
+ * <p>
+ * A MessageTemplate value which starts and ends with brackets '{', '}' will be interpreted as key for resolving from a
+ * ResourceBundle or any other lookup mechanism determined by the
+ * {@link org.apache.deltaspike.core.api.message.MessageResolver}. A small example:
  * <pre>
  * &#064;MessageTemplate("{welcome_to}")
- * </pre>
- * This will lookup a <code>welcome_to = Hello to Aruba</code> from the configured
- * resource bundle.
+ * </pre> This will lookup a <code>welcome_to = Hello to Aruba</code> from the configured resource bundle.
  * </p>
  *
- *
- * <p>MessageTemplate values without '{', '}' bracelets will be directly used
- * without resource lookup</p>
+ * <p>
+ * MessageTemplate values without '{', '}' bracelets will be directly used without resource lookup.</p>
  */
 @Target(METHOD)
 @Retention(RUNTIME)

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
index 4a837cb..5ee9098 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStage.java
@@ -29,41 +29,42 @@ import java.util.Map;
 import java.util.logging.Logger;
 
 /**
- * <p>This class is the base of all ProjectStages. A ProjectStage
- * identifies the environment the application currently runs in.
- * It provides the same functionality as the JSF-2 ProjectStage
- * but has a few additional benefits:
+ * This class is the base of all ProjectStages. A ProjectStage identifies the environment the application currently runs
+ * in. It provides the same functionality as the JSF2 ProjectStage but has a few additional benefits:
  * <ul>
- *  <li>it also works for JSF-1.0, JSF-1.1 and JSF-1.2 applications</li>
- *  <li>it also works in pure backends and unit tests without any faces-api</li>
- *  <li>it is dynamic. Everyone can add their own ProjectStages!</p>
+ * <li>it works for JSF 1.0, JSF 1.1 and JSF 1.2 applications</li>
+ * <li>it works in pure backends and unit tests without any JSF API</li>
+ * <li>it is dynamic. Everyone can add their own ProjectStages!</li>
  * </ul>
- * </p>
  *
- * <p>Technically this is kind of a 'dynamic enum'.</p>
- * <p>The following ProjectStages are provided by default</p>
+ * <p>
+ * Technically this is kind of a 'dynamic enum'.</p>
+ *
+ * <p>
+ * The following ProjectStages are provided by default:</p>
  * <ul>
- *  <li>UnitTest</li>
- *  <li>Development</li>
- *  <li>SystemTest</li>
- *  <li>IntegrationTest</li>
- *  <li>Staging</li>
- *  <li>Production</li>
+ * <li>UnitTest</li>
+ * <li>Development</li>
+ * <li>SystemTest</li>
+ * <li>IntegrationTest</li>
+ * <li>Staging</li>
+ * <li>Production</li>
  * </ul>
  *
- * <p>The following resolution mechanism is used to determine the current ProjectStage:
+ * <p>
+ * The following resolution mechanism is used to determine the current ProjectStage:</p>
  * <ul>
- *  <li>TODO specify!</li>
+ * <li>TODO specify!</li>
  * </ul>
- * </p>
  *
- * <p>Adding a new ProjectStage is done via the
- * {@link java.util.ServiceLoader} mechanism. A class deriving from {@link ProjectStage}
- * must be provided and used for creating a single static instance of it.
+ * <p>
+ * New ProjectStages can be added via the {@link java.util.ServiceLoader} mechanism. A class deriving from
+ * {@link ProjectStage} must be provided and used for creating a single static instance of it.</p>
+ *
+ * <p>
+ * Custom ProjectStages can be implemented by writing anonymous ProjectStage members into a registered
+ * {@link ProjectStageHolder} as shown in the following example:</p>
  *
- * <p>Custom ProjectStages can be implemented by writing anonymous ProjectStage
- * members into a registered {@link ProjectStageHolder} as shown in the following
- * sample:</p>
  * <pre>
  * package org.apache.deltaspike.test.core.api.projectstage;
  * public class TestProjectStages implements ProjectStageHolder {
@@ -74,28 +75,31 @@ import java.util.logging.Logger;
  *     public static final MyOtherProjectStage MyOtherProjectStage = new MyOtherProjectStage();
  * }
  * </pre>
- * <p>For activating those ProjectStages, you have to register this ProjectStageHolder class
- * to get picked up via the java.util.ServiceLoader mechanism. Simply create a file
+ *
+ * <p>
+ * To activate those ProjectStages, you have to register the ProjectStageHolder class to get picked up via the
+ * ServiceLoader mechanism. Simply create a file
  * <pre>
  * META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder
- * </pre>
- * which contains the fully qualified class name of custom ProjectStageHolder implementation:
+ * </pre> which contains the fully qualified class name of custom ProjectStageHolder implementation:
  * <pre>
  * # this class now gets picked up by java.util.ServiceLoader
  * org.apache.deltaspike.test.core.api.projectstage.TestProjectStages
  * </pre>
  * </p>
- * <p>You can use your own ProjectStages exactly the same way as all the ones provided
- * by the system:
+ *
+ * <p>
+ * You can use your own ProjectStages exactly the same way as all the ones provided by the system:
  * <pre>
  * ProjectStage myOwnPs = ProjectStage.valueOf("MyOwnProjectStage");
-   if (myOwnPs.equals(MyOwnProjectStage.MyOwnProjectStage)) ...
+ * if (myOwnPs.equals(MyOwnProjectStage.MyOwnProjectStage)) ...
  * </pre>
+ * </p>
  *
- * <p><b>Note:</b> Please note that DeltaSpike will only find {@link ProjectStageHolder}s
- * which are accessible by this very class. If you deploy the deltaspike-core jar to a
- * shared EAR classloader, it will e.g. <i>not</i> be able to register ProjectStages defined
- * in a web applications WEB-INF/classes directory!
+ * <p>
+ * <b>Note:</b> DeltaSpike will only find {@link ProjectStageHolder}s which are accessible by this very class. If you
+ * deploy the deltaspike-core jar to a shared EAR classloader, it will e.g. <i>not</i> be able to register ProjectStages
+ * defined in a web application's WEB-INF/classes directory!
  * </p>
  *
  */
@@ -159,7 +163,7 @@ public abstract class ProjectStage implements Serializable
     }
 
     /**
-     * This function exists to prevent findbugs to complain about
+     * This function exists to prevent findbugs from complaining about
      * setting a static member from a non-static function.
      *
      * @param projectStageClassName name of the project-stage
@@ -191,8 +195,9 @@ public abstract class ProjectStage implements Serializable
     }
 
     /**
-     * Exposes all registered {@link ProjectStage} implementations
-     * @return provided and custom project-stage implementations
+     * Exposes all registered {@link ProjectStage} implementations.
+     *
+     * @return provided and custom ProjectStage implementations
      */
     public static ProjectStage[] values()
     {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
index 5e8b0ff..79a7095 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/ProjectStageHolder.java
@@ -19,16 +19,15 @@
 package org.apache.deltaspike.core.api.projectstage;
 
 /**
- * <p>This is a marker interface for custom project
- * stage holders. A project stage holder is a class which
- * contains 1 or more {@link ProjectStage}s.</p>
+ * A marker interface for custom ProjectStage holders. A ProjectStage holder is a class which contains one or more
+ * {@link ProjectStage}s.
  *
- * <p>Any custom ProjectStageHolder must get registered via the
- * {@link java.util.ServiceLoader} mechanism. Simply create a file
+ * <p>
+ * Any custom ProjectStageHolder must get registered via the {@link java.util.ServiceLoader} mechanism. Simply create a
+ * file
  * <pre>
  *     META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder
- * </pre>
- * and write the fully qualified class name of your ProjectStageHolder into it.
+ * </pre> and write the fully qualified class name of your ProjectStageHolder into it.
  * </p>
  */
 public interface ProjectStageHolder

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
index 9fc17a1..bdf13a1 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/projectstage/TestStage.java
@@ -19,8 +19,8 @@
 package org.apache.deltaspike.core.api.projectstage;
 
 /**
- * Marker interface for {@link ProjectStage} implementations which are used for tests.
- * E.g. used to enable logging in all 'testing' ProjectStages.
+ * Marker interface for {@link ProjectStage} implementations which are used for tests. E.g. used to enable logging in
+ * all 'testing' ProjectStages.
  */
 public interface TestStage
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
index b977e08..a72bcf3 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanManagerProvider.java
@@ -37,27 +37,26 @@ import org.apache.deltaspike.core.util.ClassUtils;
 
 
 /**
- * <p>This class provides access to the {@link BeanManager}
- * by registering the current {@link BeanManager} in an extension and
- * making it available via a singleton factory for the current application.</p>
- * <p>This is really handy if you like to access CDI functionality
- * from places where no injection is available.</p>
- * <p>If a simple but manual bean-lookup is needed, it's easier to use the {@link BeanProvider}.</p>
- * <p/>
- * <p>As soon as an application shuts down, the reference to the {@link BeanManager} will be removed.<p>
- * <p/>
- * <p>Usage:<p/>
- * <pre>
- * BeanManager bm = BeanManagerProvider.getInstance().getBeanManager();
- * 
- * </pre>
+ * This class provides access to the {@link BeanManager} by registering the current {@link BeanManager} in an extension
+ * and making it available via a singleton factory for the current application.
+ *
+ * <p>This is really handy when you need to access CDI functionality from places where no injection is available.</p>
  *
- * <p><b>Attention:</b> This method is intended for being used in user code at runtime.
- * If this method gets used during Container boot (in an Extension), non-portable
- * behaviour results. During bootstrapping an Extension shall &#064;Inject BeanManager to get
- * access to the underlying BeanManager (see e.g. {@link #cleanupFinalBeanManagers} ).
- * This is the only way to guarantee to get the right
- * BeanManager in more complex Container scenarios.</p>
+ * <p>If a simple but manual bean lookup is needed, it's easier to use the {@link BeanProvider}.</p>
+ * 
+ * <p>As soon as an application shuts down, the reference to the {@link BeanManager} is removed.</p>
+ * 
+ * <p>
+ * Usage:
+
+ * <pre>
+ * BeanManager bm = BeanManagerProvider.getInstance().getBeanManager();</pre>
+ * </p>
+ * <p>
+ * <b>Attention:</b> This approach is intended for use in user code at runtime. If BeanManagerProvider is used during
+ * Container boot (in an Extension), non-portable behaviour results. During bootstrapping, an Extension shall
+ * &#064;Inject BeanManager to get access to the underlying BeanManager (see e.g. {@link #cleanupFinalBeanManagers}).
+ * This is the only way to guarantee that the right BeanManager is obtained in more complex Container scenarios.</p>
  */
 public class BeanManagerProvider implements Extension
 {
@@ -98,44 +97,42 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * This data container is used for storing the BeanManager for each
-     * WebApplication. This is needed in EAR or other multi-webapp scenarios
-     * if the DeltaSpike classes (jars) are provided in a shared ClassLoader.
+     * This data container is used for storing the BeanManager for each web application. This is needed in EAR or other
+     * multi-webapp scenarios when the DeltaSpike classes (jars) are provided in a shared ClassLoader.
      */
     private static class BeanManagerInfo
     {
         /**
-         * The BeanManager picked up via Extension loading
+         * The BeanManager picked up via Extension loading.
          */
         private BeanManager loadTimeBm;
 
         /**
-         * The final BeanManagers.
-         * After the container did finally boot, we first try to resolve them from JNDI,
-         * and only if we don't find any BM there we take the ones picked up at startup.
+         * The final BeanManager. After the container did finally boot, we first try to resolve them from JNDI, and only
+         * if we don't find any BM there we take the ones picked up at startup.
          */
         private BeanManager finalBm;
 
         /**
-         * Whether the CDI Application has finally booted.
-         * Please note that this is only a nearby value
-         * as there is no reliable event for this status in EE6.
+         * Whether the CDI Application has finally booted. Please note that this is only a nearby value as there is no
+         * reliable event for this status in EE6.
          */
         private boolean booted;
     }
 
     /**
-     * <p>The BeanManagerInfo for the current ClassLoader.</p>
+     * The BeanManagerInfo for the current ClassLoader.
+     * 
      * <p><b>Attention:</b> This instance must only be used through the {@link #bmpSingleton} singleton!</p>
      */
     private volatile Map<ClassLoader, BeanManagerInfo> bmInfos = new ConcurrentHashMap<ClassLoader, BeanManagerInfo>();
 
     /**
-     * Returns if the {@link BeanManagerProvider} has been initialized.
-     * Usually it isn't needed to call this method in application code.
-     * It's e.g. useful for other frameworks to check if DeltaSpike and the CDI container in general have been started.
+     * Indicates whether the {@link BeanManagerProvider} has been initialized. Usually it's not necessary to call this
+     * method in application code. It's useful e.g. for other frameworks to check if DeltaSpike and the CDI container in
+     * general have been started.
      *
-     * @return true if the bean-manager-provider is ready to be used
+     * @return true if the BeanManagerProvider is ready to be used
      */
     public static boolean isActive()
     {
@@ -143,11 +140,11 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * Allows to get the current provider instance which provides access to the current {@link BeanManager}
+     * Returns the current provider instance which provides access to the current {@link BeanManager}.
      *
-     * @throws IllegalStateException if the {@link BeanManagerProvider} isn't ready to be used.
-     * That's the case if the environment isn't configured properly and therefore the {@link AfterBeanDiscovery}
-     * hasn't be called before this method gets called.
+     * @throws IllegalStateException if the {@link BeanManagerProvider} isn't ready to be used. That's the case if the
+     *                               environment isn't configured properly and therefore the {@link AfterBeanDiscovery}
+     *                               hasn't been called before this method gets called.
      * @return the singleton BeanManagerProvider
      */
     public static BeanManagerProvider getInstance()
@@ -173,9 +170,9 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * It basically doesn't matter which of the system events we use,
-     * but basically we use the {@link AfterBeanDiscovery} event since it allows to use the
-     * {@link BeanManagerProvider} for all events which occur after the {@link AfterBeanDiscovery} event.
+     * It doesn't really matter which of the system events is used to obtain the BeanManager, but
+     * {@link AfterBeanDiscovery} has been chosen since it allows all events which occur after the
+     * {@link AfterBeanDiscovery} to use the {@link BeanManagerProvider}.
      *
      * @param afterBeanDiscovery event which we don't actually use ;)
      * @param beanManager        the BeanManager we store and make available.
@@ -189,10 +186,11 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * The active {@link BeanManager} for the current application (/{@link ClassLoader}). This method will throw an
-     * {@link IllegalStateException} if the BeanManager cannot be found.
+     * The active {@link BeanManager} for the current application (current {@link ClassLoader}). This method will throw
+     * an {@link IllegalStateException} if the BeanManager cannot be found.
+     *
+     * @return the current BeanManager, never <code>null</code>
      *
-     * @return the current bean-manager, never <code>null</code>
      * @throws IllegalStateException if the BeanManager cannot be found
      */
     public BeanManager getBeanManager()
@@ -256,18 +254,13 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * By cleaning the final BeanManager map after the Deployment got Validated,
-     * we prevent premature loading of information from JNDI in cases where the
-     * container might not be fully setup yet.
+     * By cleaning the final BeanManager map after the deployment gets validated, premature loading of information from
+     * JNDI is prevented in cases where the container might not be fully setup yet.
      *
-     * This might happen if someone uses the BeanManagerProvider during Extension
-     * startup. This should generally avoided but instead you should just use
-     * an injected BeanManager in your Extension and propagate the BeanManager
-     * via setters.
+     * This might happen if the BeanManagerProvider is used in an extension during CDI bootstrap. This should be
+     * generally avoided. Instead, an injected BeanManager should be used in Extensions and propagated using setters.
      *
-     * In EARs with multiple webapps you might get different Extensions per WAR.
-     * This depends on the container you use. By resetting <i>all</i> known
-     * BeanManagerInfos we try to
+     * In EARs with multiple webapps, each WAR might get a different Extension. This depends on the container used.
      */
     public void cleanupFinalBeanManagers(@Observes AfterDeploymentValidation adv)
     {
@@ -284,9 +277,9 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * Cleanup on container shutdown
+     * Cleanup on container shutdown.
      *
-     * @param beforeShutdown cdi shutdown event
+     * @param beforeShutdown CDI shutdown event
      */
     public void cleanupStoredBeanManagerOnShutdown(@Observes BeforeShutdown beforeShutdown)
     {
@@ -337,7 +330,7 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * Get or create the BeanManagerInfo for the given ClassLoader
+     * Get or create the BeanManagerInfo for the given ClassLoader.
      */
     private BeanManagerInfo getBeanManagerInfo(ClassLoader cl)
     {
@@ -364,10 +357,11 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * This function exists to prevent findbugs to complain about
-     * setting a static member from a non-static function.
+     * This function exists to prevent findbugs from complaining about setting a static member from a non-static
+     * function.
      *
      * @param beanManagerProvider the bean-manager-provider which should be used if there isn't an existing provider
+     *
      * @return the first BeanManagerProvider
      */
     private static BeanManagerProvider setBeanManagerProvider(BeanManagerProvider beanManagerProvider)
@@ -381,7 +375,7 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * @return whether a BeanManagerInfo for a parent classloader is available and has the booted flag set.
+     * @return whether a BeanManagerInfo for a parent ClassLoader is available and has the booted flag set.
      */
     private boolean isParentBeanManagerBooted()
     {
@@ -391,10 +385,10 @@ public class BeanManagerProvider implements Extension
     }
 
     /**
-     * This method recurses into the parent ClassLoaders and will check if a
-     * BeanManagerInfo for it exists.
-     * @return the BeanManagerInfo of the parent ClassLoader hierarchy if any exists,
-     *         or <code>null</code> if there is no {@link BeanManagerInfo} for the ClassLoaders in the hierarchy.
+     * This method recurses into the parent ClassLoaders and checks whether a BeanManagerInfo for it exists.
+     *
+     * @return the BeanManagerInfo of the parent ClassLoader hierarchy if any exists, or <code>null</code> if there is
+     *         no {@link BeanManagerInfo} for the ClassLoaders in the hierarchy.
      */
     private BeanManagerInfo getParentBeanManagerInfo(ClassLoader classLoader)
     {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
index b2ce5ab..bcf2b8d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/BeanProvider.java
@@ -41,17 +41,16 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * <p>This class contains utility methods to resolve contextual references
- * in situations where no injection is available because the
- * current class is not managed by the CDI Container. This can happen
- * in e.g. a JPA-2.0 EntityListener, a ServletFilter, a Spring managed
- * Bean, etc.</p>
+ * This class contains utility methods for resolution of contextual references in situations where no injection is
+ * available because the current class is not managed by the CDI Container. This can happen in e.g. a JPA 2.0
+ * EntityListener, a ServletFilter, a Spring managed Bean, etc.
  *
- * <p><b>Attention:</b> This method is intended for being used in user code at runtime.
- * If this method gets used during Container boot (in an Extension), non-portable
- * behaviour results. The CDI specification only allows injection of the
- * BeanManager during CDI-Container boot time.</p>
+ * <p>
+ * <b>Attention:</b> This approach is intended for use in user code at runtime. If BeanProvider is used during Container
+ * boot (in an Extension), non-portable behaviour results. The CDI specification only allows injection of the
+ * BeanManager during CDI container boot time.</p>
  *
+ * @see DependentProvider
  * @see BeanManagerProvider
  */
 @Typed()
@@ -73,26 +72,26 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a Contextual Reference by its type and qualifiers.
-     * You can use this method to get contextual references of a given type.
-     * A 'Contextual Reference' is a proxy which will automatically resolve
-     * the correct contextual instance when you access any method.</p>
-     *
-     * <p><b>Attention:</b> You shall not use this method to manually resolve a
-     * &#064;Dependent bean! The reason is that this contextual instances do usually
-     * live in the well-defined lifecycle of their injection point (the bean they got
-     * injected into). But if we manually resolve a &#064;Dependent bean, then it does <b>not</b>
-     * belong to such a well defined lifecycle (because &#064;Dependent it is not
-     * &#064;NormalScoped) and thus will not automatically be
+     * Get a Contextual Reference by its type and qualifiers. You can use this method to get contextual references of a
+     * given type. A "Contextual Reference" is a proxy which will automatically resolve the correct contextual instance
+     * when you access any method.
+     *
+     * <p>
+     * <b>Attention:</b> You shall not use this method to manually resolve a &#064;Dependent bean! The reason is that
+     * contextual instances usually live in the well-defined lifecycle of their injection point (the bean they got
+     * injected into). But if we manually resolve a &#064;Dependent bean, then it does <b>not</b> belong to such well
+     * defined lifecycle (because &#064;Dependent is not &#064;NormalScoped) and thus will not be automatically
      * destroyed at the end of the lifecycle. You need to manually destroy this contextual instance via
      * {@link javax.enterprise.context.spi.Contextual#destroy(Object, javax.enterprise.context.spi.CreationalContext)}.
-     * Thus you also need to manually store the CreationalContext and the Bean you
-     * used to create the contextual instance which this method will not provide.</p>
+     * Thus you also need to manually store the CreationalContext and the Bean you used to create the contextual
+     * instance.</p>
      *
-     * @param type the type of the bean in question
+     * @param type       the type of the bean in question
      * @param qualifiers additional qualifiers which further distinct the resolved bean
-     * @param <T> target type
+     * @param <T>        target type
+     *
      * @return the resolved Contextual Reference
+     *
      * @throws IllegalStateException if the bean could not be found.
      * @see #getContextualReference(Class, boolean, Annotation...)
      */
@@ -102,15 +101,17 @@ public final class BeanProvider
     }
 
     /**
-     * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the
-     * 'optional' parameter is set to <code>true</code>.
+     * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the 'optional' parameter
+     * is set to <code>true</code>.
+     *
+     * @param type       the type of the bean in question
+     * @param optional   if <code>true</code> it will return <code>null</code> if no bean could be found or created.
+     *                   Otherwise it will throw an {@code IllegalStateException}
+     * @param qualifiers additional qualifiers which distinguish the resolved bean
+     * @param <T>        target type
      *
-     * @param type the type of the bean in question
-     * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
-     *                 Otherwise it will throw an {@code IllegalStateException}
-     * @param qualifiers additional qualifiers which further distinguish the resolved bean
-     * @param <T> target type
      * @return the resolved Contextual Reference
+     *
      * @see #getContextualReference(Class, Annotation...)
      */
     public static <T> T getContextualReference(Class<T> type, boolean optional, Annotation... qualifiers)
@@ -121,17 +122,18 @@ public final class BeanProvider
     }
 
     /**
-     * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the
-     * 'optional' parameter is set to <code>true</code>.
-     * This method is intended for usage where the BeanManager is known, e.g. in Extensions.
+     * {@link #getContextualReference(Class, Annotation...)} which returns <code>null</code> if the 'optional' parameter
+     * is set to <code>true</code>. This method is intended for usage where the BeanManger is known, e.g. in Extensions.
      *
      * @param beanManager the BeanManager to use
-     * @param type the type of the bean in question
-     * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
-     *                 Otherwise it will throw an {@code IllegalStateException}
-     * @param qualifiers additional qualifiers which further distinguish the resolved bean
-     * @param <T> target type
+     * @param type        the type of the bean in question
+     * @param optional    if <code>true</code> it will return <code>null</code> if no bean could be found or created.
+     *                    Otherwise it will throw an {@code IllegalStateException}
+     * @param qualifiers  additional qualifiers which further distinct the resolved bean
+     * @param <T>         target type
+     *
      * @return the resolved Contextual Reference
+     *
      * @see #getContextualReference(Class, Annotation...)
      */
     public static <T> T getContextualReference(BeanManager beanManager,
@@ -156,14 +158,16 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a Contextual Reference by its EL Name.
-     * This only works for beans with the &#064;Named annotation.</p>
+     * Get a Contextual Reference by its EL Name. This only works for beans with the &#064;Named annotation.
      *
-     * <p><b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean
-     * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent beans in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+     *
+     * @param name the EL name of the bean
      *
-     * @param name     the EL name of the bean
      * @return the resolved Contextual Reference
+     *
      * @throws IllegalStateException if the bean could not be found.
      * @see #getContextualReference(String, boolean)
      */
@@ -173,15 +177,16 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a Contextual Reference by its EL Name.
-     * This only works for beans with the &#064;Named annotation.</p>
+     * Get a Contextual Reference by its EL Name. This only works for beans with the &#064;Named annotation.
      *
-     * <p><b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean
-     * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent beans in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
      *
      * @param name     the EL name of the bean
      * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
      *                 Otherwise it will throw an {@code IllegalStateException}
+     *
      * @return the resolved Contextual Reference
      */
     public static Object getContextualReference(String name, boolean optional)
@@ -190,19 +195,19 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a Contextual Reference by its EL Name.
-     * This only works for beans with the &#064;Named annotation.</p>
+     * Get a Contextual Reference by its EL Name. This only works for beans with the &#064;Named annotation.
      *
-     * <p><b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean
-     * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent beans in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
      *
-     *
-     * @param name the EL name of the bean
+     * @param name     the EL name of the bean
      * @param optional if <code>true</code> it will return <code>null</code> if no bean could be found or created.
      *                 Otherwise it will throw an {@code IllegalStateException}
-     * @param type the type of the bean in question - use {@link #getContextualReference(String, boolean)}
-     *             if the type is unknown e.g. in dyn. use-cases
-     * @param <T> target type
+     * @param type     the type of the bean in question - use {@link #getContextualReference(String, boolean)} if the
+     *                 type is unknown e.g. in dyn. use-cases
+     * @param <T>      target type
+     *
      * @return the resolved Contextual Reference
      */
     public static <T> T getContextualReference(String name, boolean optional, Class<T> type)
@@ -248,9 +253,14 @@ public final class BeanProvider
     /**
      * Get the Contextual Reference for the given bean.
      *
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent beans in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+     *
      * @param type the type of the bean in question
-     * @param bean bean-definition for the contextual-reference
-     * @param <T> target type
+     * @param bean bean definition for the contextual reference
+     * @param <T>  target type
+     *
      * @return the resolved Contextual Reference
      */
     public static <T> T getContextualReference(Class<T> type, Bean<T> bean)
@@ -265,23 +275,23 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a list of Contextual References by type independent of the qualifier
-     * (including dependent scoped beans).
+     * Get a list of Contextual References by type, regardless of qualifiers (including dependent scoped beans).
      *
-     * You can use this method to get all contextual references of a given type.
-     * A 'Contextual Reference' is a proxy which will automatically resolve
-     * the correct contextual instance when you access any method.</p>
+     * You can use this method to get all contextual references of a given type. A 'Contextual Reference' is a proxy
+     * which will automatically resolve the correct contextual instance when you access any method.
      *
-     * <p><b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean
-     * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
-     * <p><b>Attention:</b> This will also return instances of beans for which an Alternative
-     * exists! The &#064;Alternative resolving is only done via {@link BeanManager#resolve(java.util.Set)}
-     * which we cannot use in this case!</p>
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent beans in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+     * <p>
+     * <b>Attention:</b> This will also return instances of beans for which an Alternative exists! The &#064;Alternative
+     * resolving is only done via {@link BeanManager#resolve(java.util.Set)} which we cannot use in this case!</p>
+     *
+     * @param type     the type of the bean in question
+     * @param optional if <code>true</code> it will return an empty list if no bean could be found or created. Otherwise
+     *                 it will throw an {@code IllegalStateException}
+     * @param <T>      target type
      *
-     * @param type the type of the bean in question
-     * @param optional if <code>true</code> it will return an empty list if no bean could be found or created.
-     *                 Otherwise it will throw an {@code IllegalStateException}
-     * @param <T> target type
      * @return the resolved list of Contextual Reference or an empty-list if optional is true
      */
     public static <T> List<T> getContextualReferences(Class<T> type, boolean optional)
@@ -290,20 +300,22 @@ public final class BeanProvider
     }
 
     /**
-     * <p>Get a list of Contextual References by type independent of the qualifier.
+     * Get a list of Contextual References by type, regardless of the qualifier.
      *
-     * Further details are available at {@link #getContextualReferences(Class, boolean)}
-     * <p><b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean
-     * in {@link #getContextualReference(Class, boolean, java.lang.annotation.Annotation...)}!</p>
-     * <p><b>Attention:</b> This will also return instances of beans for which an Alternative
-     * exists! The &#064;Alternative resolving is only done via {@link BeanManager#resolve(java.util.Set)}
-     * which we cannot use in this case!</p>
+     * Further details are available at {@link #getContextualReferences(Class, boolean)}.
+     * <p>
+     * <b>Attention:</b> please see the notes on manually resolving &#064;Dependent bean in
+     * {@link #getContextualReference(Class, java.lang.annotation.Annotation...)}!</p>
+     * <p>
+     * <b>Attention:</b> This will also return instances of beans for which an Alternative exists! The &#064;Alternative
+     * resolving is only done via {@link BeanManager#resolve(java.util.Set)} which we cannot use in this case!</p>
      *
-     * @param type the type of the bean in question
-     * @param optional if <code>true</code> it will return an empty list if no bean could be found or created.
-     *                 Otherwise it will throw an {@code IllegalStateException}
+     * @param type                      the type of the bean in question
+     * @param optional                  if <code>true</code> it will return an empty list if no bean could be found or
+     *                                  created. Otherwise it will throw an {@code IllegalStateException}
      * @param includeDefaultScopedBeans specifies if dependent scoped beans should be included in the result
-     * @param <T> target type
+     * @param <T>                       target type
+     *
      * @return the resolved list of Contextual Reference or an empty-list if optional is true
      */
     public static <T> List<T> getContextualReferences(Class<T> type,
@@ -356,14 +368,15 @@ public final class BeanProvider
     }
 
     /**
-     * Get a set of {@link Bean} definitions by type independent of the qualifier.
+     * Get a set of {@link Bean} definitions by type, regardless of qualifiers.
      *
-     * @param type the type of the bean in question
-     * @param optional if <code>true</code> it will return an empty set if no bean could be found.
-     *                 Otherwise it will throw an {@code IllegalStateException}
-     * @param includeDefaultScopedBeans specifies if dependent scoped beans should be included in the result
-     * @param <T> target type
-     * @return the resolved set of {@link Bean} definitions or an empty-set if optional is true
+     * @param type                      the type of the bean in question
+     * @param optional                  if <code>true</code> it will return an empty set if no bean could be found.
+     *                                  Otherwise it will throw an {@code IllegalStateException}
+     * @param includeDefaultScopedBeans specifies whether dependent scoped beans should be included in the result
+     * @param <T>                       target type
+     *
+     * @return the resolved set of {@link Bean} definitions or an empty set if optional is true
      */
     public static <T> Set<Bean<T>> getBeanDefinitions(Class<T> type,
                                                       boolean optional,
@@ -410,13 +423,14 @@ public final class BeanProvider
     }
     
     /**
-     * Allows to perform dependency injection for instances which aren't managed by CDI.
+     * Performs dependency injection on an instance. Useful for instances which aren't managed by CDI.
      * <p/>
-     * Attention:<br/>
+     * <b>Attention:</b><br/>
      * The resulting instance isn't managed by CDI; only fields annotated with @Inject get initialized.
      *
      * @param instance current instance
-     * @param <T> current type
+     * @param <T>      current type
+     *
      * @return instance with injected fields (if possible - or null if the given instance is null)
      */
     @SuppressWarnings("unchecked")
@@ -474,9 +488,8 @@ public final class BeanProvider
     }
 
     /**
-     * Log a warning if the produced creational instance is of
-     * Scope &#064;Dependent as we cannot properly cleanup
-     * the contextual instance afterwards.
+     * Log a warning if the given bean is of &#064;Dependent scope as we cannot properly clean up the contextual
+     * instance afterwards.
      */
     private static void logWarningIfDependent(Bean<?> bean)
     {
@@ -488,8 +501,9 @@ public final class BeanProvider
     }
 
     /**
-     * Internal method to resolve the BeanManager via the {@link BeanManagerProvider}
-     * @return current bean-manager
+     * Internal method to resolve the BeanManager via the {@link BeanManagerProvider}.
+     *
+     * @return current BeanManager
      */
     private static BeanManager getBeanManager()
     {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
index 8e72653..2c89808 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/provider/DependentProvider.java
@@ -30,14 +30,14 @@ import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
 /**
- * A {@link Provider} for &#064;Dependent scoped contextual instances.
- * We need this to be apble to properly clean them up when they are not
- * needed anymore via the {@link #destroy()} method.
+ * A {@link Provider} for &#064;Dependent scoped contextual instances. We need this to be able to properly clean them up
+ * when they are not needed anymore via the {@link #destroy()} method.
  *
  * Instances of this class can be retrieved using the {@link BeanProvider}.
  *
- * Instances of this class are Serializable if the wrapped contextual instance
- * is Serializable.
+ * Instances of this class are Serializable if the wrapped contextual instance is Serializable.
+ *
+ * @see BeanProvider#getDependent(java.lang.Class, java.lang.annotation.Annotation...)
  */
 public class DependentProvider<T> implements Provider<T>, Serializable
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
index f1ff1db..618ae62 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/ClasspathResourceProvider.java
@@ -31,7 +31,7 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * A classpath based resource provider
+ * A classpath-based resource provider.
  */
 @ApplicationScoped
 public class ClasspathResourceProvider extends AbstractResourceProvider

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
index 8d5f5a0..72fd1f6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/FileResourceProvider.java
@@ -27,7 +27,7 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * A file based resource provider, looking for a file based on the name.
+ * A file-based resource provider, looking for a file based on the name.
  */
 @ApplicationScoped
 public class FileResourceProvider extends AbstractResourceProvider

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
index 281f59b..aaffc27 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/resourceloader/InjectableResource.java
@@ -30,6 +30,27 @@ import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.ElementType.METHOD;
 
+/**
+ * Qualifier which enables simple injection of resources into beans, eliminating the need to deal with their loading.
+ *
+ * <p>
+ * <b>Example:</b>
+ * <pre>
+ * &#064;Inject
+ * &#064;InjectableResource("myfile.properties")
+ * private Properties props;
+ *
+ * &#064;Inject
+ * &#064;InjectableResource("config.xml")
+ * private InputStream inputStream;
+ * </pre>
+ *
+ * This can be used to read files, from classpath or the file system, using two default implementations:
+ * ClasspathResourceProvider and FileResourceProvider. They can be extended as well by implementing the
+ * InjectableResourceProvider interface to allow reading from alternate sources, if needed (e.g. database LOBs, NoSQL
+ * storage areas).
+ * </p>
+ */
 @Target( { TYPE, METHOD, PARAMETER, FIELD })
 @Retention(value = RetentionPolicy.RUNTIME)
 @Documented

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
index 1274392..5d5d102 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationGroup.java
@@ -30,6 +30,11 @@ import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * 
+ * @see GroupedConversationScoped
+ * @see ConversationSubGroup
+ */
 @Target( { PARAMETER, FIELD, METHOD, CONSTRUCTOR, TYPE } )
 @Retention(RUNTIME)
 @Documented
@@ -38,7 +43,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface ConversationGroup
 {
     /**
-     * Class or interface which should be used as type-safe key for identifying the conversation-group.
+     * Class or interface which should be used as type-safe key for identification of the conversation group.
      *
      * @return class or interface which should be used as key
      */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
index 1d4ba13..30fc91d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/scope/ConversationSubGroup.java
@@ -26,45 +26,53 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Allows to close a part of a group e.g.:
+ * Represents a subgroup of a conversation group. Useful for closing a subset of {@code @GroupConversationScoped} beans
+ * in a {@code ConversationGroup}.
  *
+ * <pre>
  * public class MyGroup{}
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * &#064;ConversationScoped
+ * &#064;ConversationGroup(MyGroup.class)
  * public class BeanA {}
- * <p/>
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * &#064;ConversationScoped
+ * &#064;ConversationGroup(MyGroup.class)
  * public class BeanB {}
- * <p/>
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ *
+ * &#064;ConversationScoped
+ * &#064;ConversationGroup(MyGroup.class)
  * public class BeanC {}
- * <p/>
- * @ConversationSubGroup(of = MyGroup.class, subGroup = {BeanA.class, BeanB.class})
+ *
+ * &#064;ConversationSubGroup(of = MyGroup.class, subGroup = {BeanA.class, BeanB.class})
  * public class MySubGroup {}
- * <br/>or</br>
- * @ConversationSubGroup(subGroup = {BeanA.class, BeanB.class})
+ * </pre> or
+ * <pre>
+ * &#064;ConversationSubGroup(subGroup = {BeanA.class, BeanB.class})
  * public class MySubGroup extends MyGroup {}
- * <p/>
+ *
  * //...
  * this.groupedConversationManager.closeConversation(MySubGroup.class)
- *
- * OR it's possible to use implicit sub-groups (point to the interface(s) instead of the bean-class itself):
+ * </pre> or it's possible to use implicit subgroups (point to the interface instead of the bean class itself):
+ * <pre>
  * public interface MyUseCase {}
  *
- * @ConversationSubGroup(of = MyGroup.class, subGroup = MyUseCase.class)
+ * &#064;ConversationSubGroup(of = MyGroup.class, subGroup = MyUseCase.class)
  * public class ImplicitSubGroup {}
  *
- * @Named("myController")
- * @ConversationScoped
- * @ConversationGroup(MyGroup.class)
+ * &#064;Named("myController")
+ * &#064;ConversationScoped
+ * &#064;ConversationGroup(MyGroup.class)
  * public class MyController implements Serializable, MyUseCase
  * {
  *    //...
  * }
  * //...
  * this.groupedConversationManager.closeConversation(ImplicitSubGroup.class)
+ * </pre>
+ * 
+ * @see ConversationGroup
+ * @see GroupedConversationScoped
  */
 @Target(TYPE)
 @Retention(RUNTIME)
@@ -72,14 +80,16 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface ConversationSubGroup
 {
     /**
-     * Optionally defines the base conversation group
+     * Optionally defines the base conversation group.
+     *
      * @return base conversation group or ConversationSubGroup if the subgroup inherits from the base conversation group
      */
     Class<?> of() default ConversationSubGroup.class;
 
     /**
-     * Beans of the group which should be closed
-     * @return beans of the group which should be closed
+     * Members of the subgroup.
+     *
+     * @return beans to include in the subgroup
      */
     Class<?>[] subGroup();
 }


Mime
View raw message