deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rafab...@apache.org
Subject [3/3] deltaspike git commit: DELTASPIKE-767 Comprehensive review of javadoc: core/api
Date Tue, 11 Nov 2014 19:36:28 GMT
DELTASPIKE-767 Comprehensive review of javadoc: core/api

A non-comprehensive overview of changes (some may be from other commits):
* the term page-bean is rarely used, not used in doc at all, use view-controllers instead
* meta-data -> metadata
* English doesn't use that many dash-separated word compounds, rephrased/undashed/split as necessary
* replace occurrences of vague "the entry" or "current entry" with more descriptive ones like "this view-config"
* replace occ. of PageBean.class with ViewControllerRef.class
* make clear what's an example, e.g. SomePage.class instead of PageConfig.class which sounds like an API class
* page -> view
* "X allows to [infinitive verb]" is a non-existent construct in English syntax. Corrected all occurrences. It's meaningless in an API documentation (javadoc), since every single method "allows" the user to do something.
* Moved TODOs from javadocs to comments
* formatting (120 char line length)
* reorganized ConfigProperty
* less of "we", more passive forms
* refactored BeanProvider's javadoc, warnings about dependent, etc.
* ConversationSubGroup shouldn't only mention conversation closing
* added some links (@see) to enable discovery of features in javadoc
* removed some defensive-sounding design decision arguments ("this class exists because..."), reformulated to convey purpose
* configuration.ordinal -> deltaspike_ordinal
* (Solder) Catch -> Exception Control


Project: http://git-wip-us.apache.org/repos/asf/deltaspike/repo
Commit: http://git-wip-us.apache.org/repos/asf/deltaspike/commit/34b713b4
Tree: http://git-wip-us.apache.org/repos/asf/deltaspike/tree/34b713b4
Diff: http://git-wip-us.apache.org/repos/asf/deltaspike/diff/34b713b4

Branch: refs/heads/master
Commit: 34b713b41cc1a237cb128ac24207b76a6bb81d0c
Parents: 8138f1b
Author: Ron Smeral <rsmeral@redhat.com>
Authored: Sat Oct 25 03:09:34 2014 +0200
Committer: Rafael Benevides <rafabene@gmail.com>
Committed: Tue Nov 11 17:31:21 2014 -0200

----------------------------------------------------------------------
 .../deltaspike/core/api/common/DeltaSpike.java  |   2 +-
 .../core/api/config/ConfigProperty.java         |  74 +++----
 .../core/api/config/ConfigResolver.java         | 163 ++++++++------
 .../core/api/config/DeltaSpikeConfig.java       |  17 +-
 .../core/api/config/PropertyFileConfig.java     |  31 ++-
 .../core/api/config/PropertyLoader.java         |  42 ++--
 .../core/api/config/view/DefaultErrorView.java  |   8 +-
 .../core/api/config/view/ViewConfig.java        |   4 +-
 .../core/api/config/view/ViewRef.java           |   9 +-
 .../api/config/view/controller/InitView.java    |   4 +-
 .../config/view/controller/PostRenderView.java  |   4 +-
 .../config/view/controller/PreRenderView.java   |   4 +-
 .../config/view/controller/PreViewAction.java   |   5 +-
 .../view/controller/ViewControllerRef.java      |  21 +-
 .../api/config/view/metadata/Aggregated.java    |  19 +-
 .../view/metadata/CallbackDescriptor.java       |   4 +-
 .../config/view/metadata/ConfigDescriptor.java  |  58 +++--
 .../config/view/metadata/DefaultCallback.java   |  46 ++--
 .../metadata/ExecutableCallbackDescriptor.java  |   6 +-
 .../view/metadata/InlineViewMetaData.java       |  11 +
 .../view/metadata/SimpleCallbackDescriptor.java |   4 +-
 .../config/view/metadata/SkipMetaDataMerge.java |   8 +-
 .../view/metadata/ViewConfigDescriptor.java     |   9 +-
 .../view/metadata/ViewConfigResolver.java       |  39 ++--
 .../api/config/view/metadata/ViewMetaData.java  |   8 +-
 .../view/navigation/NavigationParameter.java    |  13 +-
 .../navigation/NavigationParameterContext.java  |   2 +-
 .../view/navigation/ViewNavigationHandler.java  |   4 +-
 .../event/PreViewConfigNavigateEvent.java       |   8 +-
 .../api/exception/control/BeforeHandles.java    |  16 +-
 .../api/exception/control/ExceptionHandler.java |   3 +
 .../control/ExceptionHandlingFlow.java          |   2 +-
 .../api/exception/control/HandlerMethod.java    |   5 +-
 .../core/api/exception/control/Handles.java     |  15 +-
 .../exception/control/event/ExceptionEvent.java |   4 +-
 .../control/event/ExceptionToCatchEvent.java    |   7 +-
 .../deltaspike/core/api/exclude/Exclude.java    |  49 +++--
 .../BasePropertyExpressionInterpreter.java      |   2 +-
 .../api/interpreter/ExpressionInterpreter.java  |  13 +-
 .../api/interpreter/SimpleOperationEnum.java    |   2 +-
 .../deltaspike/core/api/jmx/JmxBroadcaster.java |   5 +-
 .../deltaspike/core/api/jmx/JmxManaged.java     |   6 +-
 .../apache/deltaspike/core/api/jmx/MBean.java   |  14 +-
 .../core/api/message/LocaleResolver.java        |  13 +-
 .../deltaspike/core/api/message/Message.java    |  64 +++---
 .../core/api/message/MessageBundle.java         |  48 ++---
 .../core/api/message/MessageContext.java        |  17 +-
 .../core/api/message/MessageContextConfig.java  |  34 +--
 .../core/api/message/MessageInterpolator.java   |  26 ++-
 .../core/api/message/MessageResolver.java       |  13 +-
 .../core/api/message/MessageTemplate.java       |  29 ++-
 .../core/api/projectstage/ProjectStage.java     |  83 ++++----
 .../api/projectstage/ProjectStageHolder.java    |  13 +-
 .../core/api/projectstage/TestStage.java        |   4 +-
 .../core/api/provider/BeanManagerProvider.java  | 124 ++++++-----
 .../core/api/provider/BeanProvider.java         | 212 ++++++++++---------
 .../core/api/provider/DependentProvider.java    |  10 +-
 .../ClasspathResourceProvider.java              |   2 +-
 .../resourceloader/FileResourceProvider.java    |   2 +-
 .../api/resourceloader/InjectableResource.java  |  21 ++
 .../core/api/scope/ConversationGroup.java       |   7 +-
 .../core/api/scope/ConversationSubGroup.java    |  56 +++--
 .../core/api/scope/ViewAccessScoped.java        |   6 +-
 .../deltaspike/core/api/scope/WindowScoped.java |   2 +-
 64 files changed, 840 insertions(+), 716 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
index 5811fa1..4f1d106 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/common/DeltaSpike.java
@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
 import javax.inject.Qualifier;
 
 /**
- * Common qualifier to manage co-existence of DeltaSpike features and JavaEE features.
+ * Common qualifier to manage co-existence of DeltaSpike features and Java EE features.
  */
 @Target( { TYPE, METHOD, PARAMETER, FIELD })
 @Retention(value = RetentionPolicy.RUNTIME)

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
index f1f44f5..e32fbda 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigProperty.java
@@ -32,88 +32,75 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * <p>This Qualifier allows to use the DeltaSpike configuration mechanism
- * via simple injection.</p>
- *
- * <p>Example 1:
+ * This Qualifier allows simple injection of configuration properties through the DeltaSpike configuration 
+ * mechanism.
+ * <p>
+ * A default implementation is provided in DeltaSpike for basic String injection points:
  * <pre>
  *   &#064;Inject &#064;ConfigProperty(name=&quot;locationId&quot;)
  *   private String locationId;
  * </pre>
  * </p>
- *
- * <p>Example 2 (the type-safe alternative):
+ * <p>
+ * It's possible to use config properties in a type-safe manner, which requires a custom producer:
  *
  * <pre>
- *   &#064;Target({ FIELD, METHOD })
+ *   &#064;Target({FIELD, METHOD})
  *   &#064;Retention(RUNTIME)
  *   &#064;ConfigProperty(name = "locationId")
- *   // alternative to null check in the producer:
- *   // &#064;ConfigProperty(name = "locationId", defaultValue = "LOCATION_X")
  *   &#064;Qualifier
- *   public &#064;interface Location
- *   {
+ *   public &#064;interface Location {
  *   }
  * </pre>
- * </p>
  *
- * Depending on the producer it's possible to use a String or a custom type like an enum at the injection point.
- * <p/>
- * With a String:
  * <pre>
  *   &#064;Location
  *   private String locationId;
  * </pre>
  *
- * With a custom type:
- * <pre>
- *   &#064;Inject
- *   &#064;Location
- *   private LocationId locationId;
- * </pre>
- * <p>In any case a custom producer is needed.
- * {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can be used as an base for custom
- * producers.
- * Producer for the configured String:
- * <pre>
+ *  <pre>
  *   &#064;ApplicationScoped
- *   public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer
- *   {
+ *   public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer {
  *     &#064;Produces
  *     &#064;Dependent
  *     &#064;Location
- *     public String produceLocationId(InjectionPoint injectionPoint)
- *     {
+ *     public String produceLocationId(InjectionPoint injectionPoint) {
  *       String configuredValue = getStringPropertyValue(injectionPoint);
- *       if (configuredValue == null)
- *       {
+ *       if (configuredValue == null) {
  *         return null;
  *       }
  *       return configuredValue;
  *     }
  *   }
  * </pre>
+ * </p>
+ * <p>
+ * Producers can be implemented to support other types of injection points:
+ * <pre>
+ *   &#064;Inject
+ *   &#064;Location
+ *   private LocationId locationId;
+ * </pre>
  *
- * Producer for a custom type:
  * <pre>
  *   &#064;ApplicationScoped
- *   public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer
- *   {
+ *   public class CustomConfigPropertyProducer extends BaseConfigPropertyProducer {
  *     &#064;Produces
  *     &#064;Dependent
  *     &#064;Location
- *     public LocationId produceLocationId(InjectionPoint injectionPoint)
- *     {
+ *     public LocationId produceLocationId(InjectionPoint injectionPoint) {
  *       String configuredValue = getStringPropertyValue(injectionPoint);
- *       if (configuredValue == null)
- *       {
+ *       if (configuredValue == null) {
  *         return null;
  *       }
  *       return LocationId.valueOf(configuredValue.trim().toUpperCase());
  *     }
  *   }
  * </pre>
- *
+ * </p>
+ * For custom producer implementations, {@link org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer} can
+ * be used as the base class.
+ * 
  * @see org.apache.deltaspike.core.api.config.ConfigResolver
  * @see org.apache.deltaspike.core.spi.config.BaseConfigPropertyProducer
  */
@@ -124,13 +111,13 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface ConfigProperty
 {
     /**
-     * This constant is a workaround for the java restriction that Annotation values
-     * cannot be set to null. Do not use this String in your configuration...
+     * This constant is a workaround for the java restriction that Annotation values cannot be set to null. Do not use
+     * this String in your configuration.
      */
     String NULL = "org.apache.deltaspike.NullValueMarker";
 
     /**
-     * Name/key of the property
+     * Name/key of the property.
      * @return name of the property
      */
     @Nonbinding
@@ -138,6 +125,7 @@ public @interface ConfigProperty
 
     /**
      * <b>Optional</b> default value.
+     *
      * @return the default value which should be used if no config value could be found
      */
     @Nonbinding

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
index ae37147..c70557b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/ConfigResolver.java
@@ -39,11 +39,20 @@ import org.apache.deltaspike.core.util.ProjectStageProducer;
 import org.apache.deltaspike.core.util.ServiceUtils;
 
 /**
- * <p>Resolve the configuration via their well defined ordinals.</p>
+ * The main entry point to the DeltaSpike configuration mechanism.
  *
- * <p>You can provide your own lookup paths by implementing
- * and registering additional {@link PropertyFileConfig} or
+ * <p>
+ * Resolves configured values of properties by going through the list of configured {@link ConfigSource}s and using the
+ * one with the highest ordinal. If multiple {@link ConfigSource}s have the same ordinal, their order is undefined.</p>
+ *
+ * <p>
+ * You can provide your own lookup paths by implementing and registering additional {@link PropertyFileConfig} or
  * {@link ConfigSource} or {@link ConfigSourceProvider} implementations.</p>
+ *
+ * <p>
+ * The resolved configuration is also accessible by simple injection using the {@link ConfigProperty} qualifier.</p>
+ *
+ * @see <a href="http://deltaspike.apache.org/documentation/configuration.html">DeltaSpike Configuration Mechanism</a>
  */
 @Typed()
 public final class ConfigResolver
@@ -96,7 +105,7 @@ public final class ConfigResolver
     }
 
     /**
-     * Clear all ConfigSources for the current ClassLoader
+     * Clear all ConfigSources for the current ClassLoader.
      */
     public static synchronized void freeConfigSources()
     {
@@ -104,9 +113,9 @@ public final class ConfigResolver
     }
 
     /**
-     * Add a {@link ConfigFilter} to the ConfigResolver.
-     * This will only affect the current WebApp
-     * (or more precisely the current ClassLoader and it's children).
+     * Add a {@link ConfigFilter} to the ConfigResolver. This will only affect the current WebApp (or more precisely the
+     * current ClassLoader and it's children).
+     *
      * @param configFilter
      */
     public static void addConfigFilter(ConfigFilter configFilter)
@@ -132,14 +141,14 @@ public final class ConfigResolver
     }
 
     /**
-     * Resolve the property value by going through the list of configured {@link ConfigSource}s
-     * and use the one with the highest priority. If no configured value has been found that
-     * way we will use the defaultValue.
+     * {@link #getPropertyValue(java.lang.String)} which returns the provided default value if no configured value can
+     * be found (<code>null</code> or empty).
      *
-     * @param key the property key.
-     * @param defaultValue will be used if no configured value for the key could be found.
-     * @return the configured property value from the {@link ConfigSource} with the highest ordinal or
-     *         the defaultValue if there is no value explicitly configured.
+     * @param key          the property key
+     * @param defaultValue fallback value
+     *
+     * @return the configured property value from the {@link ConfigSource} with the highest ordinal or the defaultValue
+     *         if there is no value explicitly configured
      */
     public static String getPropertyValue(String key, String defaultValue)
     {
@@ -149,12 +158,12 @@ public final class ConfigResolver
     }
 
     /**
-     * Resolve the property value by going through the list of configured {@link ConfigSource}s
-     * and use the one with the highest priority.
+     * Resolves the value configured for the given key.
+     *
+     * @param key the property key
      *
-     * @param key the property key.
-     * @return the configured property value from the {@link ConfigSource} with the highest ordinal or
-     * null if there is no configured value for it.
+     * @return the configured property value from the {@link ConfigSource} with the highest ordinal or null if there is
+     *         no configured value for it
      */
     public static String getPropertyValue(String key)
     {
@@ -180,18 +189,22 @@ public final class ConfigResolver
     }
 
     /**
-     * <p>Search for the configured value in all {@link ConfigSource}s and take the
-     * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}
-     * into account.</p>
+     * Resolves the value configured for the given key in the current
+     * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}.
+     *
+     * <p>
+     * First, it will search for a value configured for the given key suffixed with the current ProjectStage (e.g.
+     * 'myproject.myconfig.Production'), and in case this value is not found (null or empty), it will look up the given
+     * key without any suffix.</p>
      *
-     * <p>It first will search if there is a configured value of the given key prefixed
-     * with the current ProjectStage (e.g. 'myproject.myconfig.Production') and if this didn't
-     * find anything it will lookup the given key without any prefix.</p>
+     * <p>
+     * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+     * used to determine the ProjectStage itself.</p>
      *
-     * <p><b>Attention</b> This method must only be used after all ConfigSources
-     * got registered and it also must not be used to determine the ProjectStage itself.</p>
      * @param key
-     * @return the configured value or if non found the defaultValue
+     *
+     * @return the value configured for {@code <given key>.<current project stage>}, or just the configured value of
+     *         {@code <given key>} if the project-stage-specific value is not found (null or empty)
      *
      */
     public static String getProjectStageAwarePropertyValue(String key)
@@ -207,10 +220,12 @@ public final class ConfigResolver
         return value;
     }
     /**
-     * {@link #getProjectStageAwarePropertyValue(String)} which returns the defaultValue
-     * if the property is <code>null</code> or empty.
+     * {@link #getProjectStageAwarePropertyValue(String)} which returns the provided default value if no configured
+     * value can be found (<code>null</code> or empty).
+     *
      * @param key
-     * @param defaultValue
+     * @param defaultValue fallback value
+     *
      * @return the configured value or if non found the defaultValue
      *
      */
@@ -222,37 +237,42 @@ public final class ConfigResolver
     }
 
     /**
-     * <p>Search for the configured value in all {@link ConfigSource}s and take the
-     * current {@link org.apache.deltaspike.core.api.projectstage.ProjectStage}
-     * and the value configured for the given property into account.</p>
-     *
-     * <p>The first step is to resolve the value of the given property. This will
-     * take the current ProjectStage into account. E.g. given the property is 'dbvendor'
-     * and the ProjectStage is 'UnitTest', the first lookup is
-     * <ul><li>'dbvendor.UnitTest'</li></ul>.
-     * If this value is not found then we will do a 2nd lookup for
-     * <ul><li>'dbvendor'</li></ul></p>
+     * Resolves the value configured for the given key, parameterized by the current
+     * {@link org.apache.deltaspike.core.api.projectstage.ProjectStage} and by the value of a second property.
      *
-     * <p>If a value was found for the given property (e.g. dbvendor = 'mysql'
-     * then we will use this value to lookup in the following order until we
-     * found a non-null value. If there was no value found for the property
-     * we will only do the key+ProjectStage and key lookup.
-     * In the following sample 'dataSource' is used as key parameter:
+     * <p>
+     * <b>Example:</b><br/>
+     * Suppose the current ProjectStage is {@code UnitTest} and we are looking for the value of {@code datasource}
+     * parameterized by the configured {@code dbvendor}.
+     * </p>
+     * <p>
+     * The first step is to resolve the value of the second property, {@code dbvendor}. This will also take the current
+     * ProjectStage into account. The following lookup is performed:
+     * <ul><li>dbvendor.UnitTest</li></ul>
+     * and if this value is not found then we will do a 2nd lookup for
+     * <ul><li>dbvendor</li></ul></p>
      *
+     * <p>
+     * If a value was found for the second property (e.g. dbvendor = 'mysql') then we will use its value for the main
+     * lookup. If no value is found for the parameterized key {@code <key>.<second property value>.<project stage>}, we
+     * will do the {@code <key>.<second property value>}, then {@code <key>.<project stage>} and finally a {@code <key>}
+     * lookup:
      * <ul>
-     *      <li>'datasource.mysql.UnitTest'</li>
-     *      <li>'datasource.mysql'</li>
-     *      <li>'datasource.UnitTest'</li>
-     *      <li>'datasource'</li>
+     * <li>datasource.mysql.UnitTest</li>
+     * <li>datasource.mysql</li>
+     * <li>datasource.UnitTest</li>
+     * <li>datasource</li>
      * </ul>
      * </p>
      *
+     * <p>
+     * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+     * used to determine the ProjectStage itself.</p>
      *
-     * <p><b>Attention</b> This method must only be used after all ConfigSources
-     * got registered and it also must not be used to determine the ProjectStage itself.</p>
      * @param key
-     * @param property the property to look up first
-     * @return the configured value or if non found the defaultValue
+     * @param property the property to look up first and use as the parameter for the main lookup
+     *
+     * @return the configured value or null if no value is found for any of the key variants
      *
      */
     public static String getPropertyAwarePropertyValue(String key, String property)
@@ -274,15 +294,21 @@ public final class ConfigResolver
         return value;
     }
 
-    /*
-     * <p><b>Attention</b> This method must only be used after all ConfigSources
-     * got registered and it also must not be used to determine the ProjectStage itself.</p>
+    /**
+     * {@link #getPropertyAwarePropertyValue(java.lang.String, java.lang.String)} which returns the provided default
+     * value if no configured value can be found (<code>null</code> or empty).
+     *
+     * <p>
+     * <b>Attention</b> This method must only be used after all ConfigSources got registered and it also must not be
+     * used to determine the ProjectStage itself.</p>
+     *
      * @param key
-     * @param property the property to look up first
-     * @param defaultValue
+     * @param property     the property to look up first and use as the parameter for the main lookup
+     * @param defaultValue fallback value
+     *
      * @return the configured value or if non found the defaultValue
      *
-    */
+     */
     public static String getPropertyAwarePropertyValue(String key, String property, String defaultValue)
     {
         String value = getPropertyAwarePropertyValue(key, property);
@@ -291,12 +317,12 @@ public final class ConfigResolver
     }
 
     /**
-     * Resolve all values for the given key, from all registered ConfigSources ordered by their
-     * ordinal value in ascending ways. If more {@link ConfigSource}s have the same ordinal, their
-     * order is undefined.
+     * Resolve all values for the given key.
+     *
+     * @param key
+     *
+     * @return a List of all found property values, sorted by their ordinal in ascending order
      *
-     * @param key under which configuration is stored
-     * @return List with all found property values, sorted in ascending order of their ordinal.
      * @see org.apache.deltaspike.core.spi.config.ConfigSource#getOrdinal()
      */
     public static List<String> getAllPropertyValues(String key)
@@ -323,6 +349,13 @@ public final class ConfigResolver
         return result;
     }
 
+    /**
+     * Returns a Map of all properties from all scannable config sources. The values of the properties reflect the
+     * values that would be obtained by a call to {@link #getPropertyValue(java.lang.String)}, that is, the value of the
+     * property from the ConfigSource with the highest ordinal.
+     *
+     * @see ConfigSource#isScannable()
+     */
     public static Map<String, String> getAllProperties()
     {
         // must use a new list because Arrays.asList() is resistant to sorting on some JVMs:

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
index 87ca2ce..3b51992 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/DeltaSpikeConfig.java
@@ -21,18 +21,17 @@ package org.apache.deltaspike.core.api.config;
 import java.io.Serializable;
 
 /**
- * <p>Marker interface for all type-safe framework configs.</p>
+ * Marker interface for all classes used for configuration of DeltaSpike itself.
  *
- * <p>All DeltaSpike Configuration objects implement this interface
- * so they can be found more easily. There is no other
+ * <p>
+ * All DeltaSpike configuration objects implement this interface so they can be found more easily. There is no other
  * functionality implied with this interface.</p>
  *
- * <p>DeltaSpike uses a <i>Typesafe Configuration</i> approach.
- * Instead of writing a properties file or XML, you just implement
- * one of the configuration interfaces which will then be picked up as
- * CDI bean. If there is already a default configuration for
- * some functionality in DeltaSpike, you can use &#064;Specializes or
- * &#064;Alternative to change those.</p>
+ * <p>
+ * DeltaSpike uses a <i>type-safe configuration</i> approach. Instead of writing a properties file or XML, you just
+ * implement one of the configuration interfaces which will then be picked up as a CDI bean. If there is already a
+ * default configuration for some functionality in DeltaSpike, you can use &#064;Specializes or &#064;Alternative to
+ * change those.</p>
  */
 public interface DeltaSpikeConfig extends Serializable
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
index 0d0a883..216ebe7 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyFileConfig.java
@@ -19,29 +19,26 @@
 package org.apache.deltaspike.core.api.config;
 
 /**
- *  <p>If you implement this interface inside a Bean Archive
- *  (a JAR or ClassPath entry with a META-INF/beans.xml file),
- *  the property files with the given file name
- *  will be registered as {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.</p>
+ * <p>
+ * If you implement this interface inside a Bean Archive (a JAR or ClassPath entry with a META-INF/beans.xml file), the
+ * property files with the given file name will be registered as
+ * {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.</p>
  *
- *  <p>DeltaSpike will automatically pickup all the implementations
- *  during the {@link javax.enterprise.inject.spi.ProcessAnnotatedType}
- *  phase and create a new instance via reflection. Thus the
- *  implementations will need a non-private default constructor.
- *  There is <b>no</b> CDI injection being performed in those instances!
- *  The scope of the implementations will also be ignored as they will
- *  not get picked up as CDI beans.</p>
+ * <p>
+ * DeltaSpike will automatically pick up all the implementations during the
+ * {@link javax.enterprise.inject.spi.ProcessAnnotatedType} phase and create a new instance via reflection. Thus the
+ * implementations will need a non-private default constructor. There is <b>no</b> CDI injection being performed in
+ * those instances! The scope of the implementations will also be ignored as they will not get picked up as CDI
+ * beans.</p>
  *
- *  <p>Please note that the configuration will only be available
- *  after the boot is finished. This means that you cannot use
- *  this configuration inside a CDI Extension before the boot
- *  is finished!</p>
+ * <p>
+ * Please note that the configuration will only be available after the boot is finished. This means that you cannot use
+ * this configuration inside a CDI Extension before the boot is finished!</p>
  */
 public interface PropertyFileConfig extends DeltaSpikeConfig
 {
     /**
-     * All the property files on the classpath which have this
-     * name will get picked up and registered as
+     * All the property files on the classpath which have this name will get picked up and registered as
      * {@link org.apache.deltaspike.core.spi.config.ConfigSource}s.
      *
      * @return the full file name (including path) of the property files to pick up.

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
index ecd7291..eb777da 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/PropertyLoader.java
@@ -35,13 +35,14 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * <p>Utility class to load configuration properties via a list of
- * artibrary property files by a well defined order.</p>
+ * Utility class to load configuration properties via arbitrary property files in a well defined order.
  *
- * <p>This will also pick up property files which are post-fixed with
- * a -$projectStage.properties </p>
- * <p>User configurations should start with 'configuration.ordinal'
- * greater than 100.</p>
+ * <p>
+ * This will also pick up property files with names suffixed with {@code -<project stage>}, e.g.
+ * myconfig-Production.properties.</p>
+ * <p>
+ * User configurations should have {@code deltaspike_ordinal} as the first property, with a value greater than
+ * 100.</p>
  *
  */
 public class PropertyLoader
@@ -61,24 +62,25 @@ public class PropertyLoader
     }
 
     /**
-     * <p>Look for all property files with the given name (e.g. 'myconfig.properties') in
-     * the classpath. Then load all properties files and sort them by their ascending
-     * configuration order and apply them in this order.</p>
+     * Looks for all properties files with the given name in the classpath, loads them in ascending order determined by
+     * their ordinal and merges them.
      *
-     * <p>The idea is to be able to 'override' properties by just providing
-     * a new properties file with the same name but a higher 'deltaspike_ordinal'
-     * than the old one.</p>
+     * <p>
+     * The idea is to be able to override properties by just providing a new properties file with the same name but a
+     * higher 'deltaspike_ordinal' than the old one.</p>
      *
-     * <p>If a property file defines no 'configuration.ordinal' property than a default
-     * value of {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive
-     * default which is provided by the system parsing for the configuration should
-     * have a 'configuration.ordinal' value lower than 10. In most cases a value of 1</p>
+     * <p>
+     * If a property file defines no 'deltaspike_ordinal' property than a default value of
+     * {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} is assumed. Any sensitive default which is provided by the system
+     * parsing for the configuration should have a 'deltaspike_ordinal' value lower than 10. In most cases a value of
+     * 1.</p>
      *
-     * <p>If 2 property files have the same ordinal 'configuraiton.order' the outcome
-     * is not really defined. The Properties file which got found first will be
-     * processed first and thus get overwritten by the one found later.</p> 
+     * <p>
+     * If two property files have the same 'deltaspike_ordinal', their order is undefined. The Properties file which
+     * gets found first will be processed first and thus gets overwritten by the one found later.</p>
      *
      * @param propertyFileName the name of the properties file, without the extension '.properties'
+     *
      * @return the final property values
      */
     public static synchronized Properties getProperties(String propertyFileName)
@@ -205,7 +207,7 @@ public class PropertyLoader
     }
 
     /**
-     * Determine the 'configuration.ordinal' of the given properties.
+     * Determine the 'deltaspike_ordinal' of the given properties.
      * {@link #CONFIGURATION_ORDINAL_DEFAULT_VALUE} if
      * {@link ConfigSource#DELTASPIKE_ORDINAL} is not set in the
      * Properties file.

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
index 5305907..9bdf5c6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/DefaultErrorView.java
@@ -20,11 +20,9 @@ package org.apache.deltaspike.core.api.config.view;
 
 /**
  * Abstract class which marks an error view.
- * <p/>
- * It's an abstract class instead of an interface,
- * because you can use it for navigation (which is restricted to classes).
- * (Since only the final page should be a class and for the rest it's recommended to use interfaces,
- * it isn't a problem/restriction.)
+ *
+ * It's an abstract class instead of an interface, because it can be used for navigation (which is restricted to
+ * classes).
  */
 public abstract class DefaultErrorView implements ViewConfig
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
index 66db48a..ab8a017 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewConfig.java
@@ -19,8 +19,8 @@
 package org.apache.deltaspike.core.api.config.view;
 
 /**
- * Marker interface for type-safe view-config classes.
- * Required for view-configs which represent a (logical) page and optional for the rest (e.g. folder-configs).
+ * Marker interface for type-safe view-config classes. Required for view-configs which represent a (logical) page and
+ * optional for the rest (e.g. folder-configs).
  */
 public interface ViewConfig
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
index 8c4a786..4634631 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/ViewRef.java
@@ -35,7 +35,10 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * Allows to reference a view-config
+ * A reference to a view-config, applied on a view-controller. The opposite direction of {@link ViewControllerRef}.
+ *
+ * ViewRef annotation instances are not present at runtime as metadata, they are instead transformed to
+ * ViewControllerRef instances during deployment.
  */
 
 @Target({ TYPE, METHOD })
@@ -52,9 +55,9 @@ public @interface ViewRef
     }
 
     /**
-     * Specifies the pages via type-safe {@link ViewConfig}.
+     * Specifies the views to bind to the view-controller.
      *
-     * @return views which should be aware of the bean or observer
+     * @return {@link ViewConfig}s of views bound to the view-controller
      */
     @Nonbinding Class<? extends ViewConfig>[] config();
 

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
index 4bb4e44..7764c1e 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/InitView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked as soon as a view has been initialized.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked as soon as a view
+ * has been initialized.
  */
 @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/config/view/controller/PostRenderView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
index 6148759..a6b4f23 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PostRenderView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked after the view gets rendered.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked after the view gets
+ * rendered.
  */
 @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/config/view/controller/PreRenderView.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
index 0bde410..baf8e68 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreRenderView.java
@@ -26,8 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked before the view gets rendered.
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the view gets
+ * rendered.
  */
 @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/config/view/controller/PreViewAction.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
index 0d835cb..8ced102 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/PreViewAction.java
@@ -26,9 +26,8 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * View-controller annotation for page-beans.
- * Methods annotated with this annotation will be invoked before the method binding gets invoked.
- * Usually only used for using a callback in the page-bean in parallel with 3rd party flow-engines
+ * Callback annotation for view-controllers. Methods annotated with this annotation will be invoked before the method
+ * binding gets invoked. Can be used as a callback in a view-controller in parallel with 3rd party flow-engines.
  */
 @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/config/view/controller/ViewControllerRef.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
index e107db1..a767e84 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/controller/ViewControllerRef.java
@@ -18,11 +18,6 @@
  */
 package org.apache.deltaspike.core.api.config.view.controller;
 
-/**
- * Specifies one or more page-beans via the type-safe view-config.
- * Such page beans support e.g. the view-controller annotations.
- */
-
 import org.apache.deltaspike.core.api.config.view.metadata.SimpleCallbackDescriptor;
 import org.apache.deltaspike.core.api.config.view.metadata.ViewMetaData;
 import org.apache.deltaspike.core.spi.config.view.ConfigPreProcessor;
@@ -36,6 +31,10 @@ import java.lang.annotation.Target;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Specifies one or more view-controllers for the view-config which has this annotation applied. View-controllers can
+ * handle callbacks like {@link InitView}, {@link PreRenderView}, etc.
+ */
 //don't use @Inherited
 @Target(TYPE)
 @Retention(RUNTIME)
@@ -45,19 +44,17 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface ViewControllerRef
 {
     /**
-     * Class of the page-bean
+     * Class of the view-controller.
      *
-     * @return class of the page-bean
+     * @return class of the view-controller
      */
     Class<?> value();
 
     /**
-     * Currently not implemented
-     *
-     *
-     * Optional name of the page-bean
+     * Currently not implemented. 
+     * Optional name of the view-controller.
      *
-     * @return name of the page-bean
+     * @return name of the view-controller
      */
     //TODO
     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/config/view/metadata/Aggregated.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
index c163219..a0c6aca 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/Aggregated.java
@@ -26,20 +26,23 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This annotation can be used to mark annotations as aggregated meta-data.
- * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter.
- * E.g. DefaultConfigNodeConverter uses the result stored in ViewConfigNode#getInheritedMetaData to replace
- * default- (/ null-) values of "higher" levels with custom values of "lower" levels,
- * if #value is 'true'.
+ * Marks view-metadata annotations or their fields as aggregated metadata. That results in retention of multiple
+ * instances of such annotation per view instead of the metadata getting overriden by lower levels.
+ *
+ * Core just provides this annotation, but the concrete behaviour is defined by a concrete ConfigNodeConverter. E.g.
+ * DefaultConfigNodeConverter uses the result stored in
+ * {@link org.apache.deltaspike.core.spi.config.view.ViewConfigNode#getInheritedMetaData} to replace default- (/ null-)
+ * values of "higher" levels with custom values of "lower" levels, if #value is 'true'.
  */
-@Target({ ANNOTATION_TYPE }) //TODO re-visit and discuss method-level (for annotation-attributes)
+//TODO re-visit and discuss method-level (for annotation-attributes)
+@Target({ ANNOTATION_TYPE })
 @Retention(RUNTIME)
 @Documented
 public @interface Aggregated
 {
     /**
-     * @return false to override the same meta-data type of the parent view-config and
-     *         true to allow multiple instances of a meta-data per view
+     * @return false to override the same metadata type of the parent view-config, and true to allow multiple instances
+     *         of a metadata per view
      */
     boolean value();
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
index cb7e1c8..848c5aa 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/CallbackDescriptor.java
@@ -31,8 +31,8 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Basic descriptor for a given class and callback-type.
- * It finds and caches the method/s of the given class which are annotated with the given callback-type.
+ * Basic descriptor for a given class and callback type. It finds and caches the method(s) of the given class which are
+ * annotated with the given callback-type.
  */
 public abstract class CallbackDescriptor
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
index df4383b..401dfe5 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ConfigDescriptor.java
@@ -22,51 +22,60 @@ import java.lang.annotation.Annotation;
 import java.util.List;
 
 /**
- * Base descriptor for all type-safe view-configs which represents the
- * config-class and meta-data, callbacks,... provided by/bound to this class.
+ * Base descriptor for all type-safe view-configs which describes the config class, metadata, callbacks and other
+ * properties of a view-config.
+ *
+ * @param <CT> class of the view-config
  */
-public interface ConfigDescriptor<CT /*config type*/>
+public interface ConfigDescriptor<CT>
 {
     Class<? extends CT> getConfigClass();
 
     /**
-     * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated
-     * with {@link ViewMetaData}
+     * Metadata configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are inherited
+     * or directly present on the view-config class.
      *
-     * @return meta-data of the current entry
+     * @return metadata of this view-config
      */
     List<Annotation> getMetaData();
 
     /**
-     * Meta-data which is configured for the entry. It allows to provide and resolve meta-data annotated
-     * with {@link ViewMetaData}
+     * Metadata which is configured for this view-config. Resolves {@link ViewMetaData}-annotated annotations which are
+     * inherited or directly present on the view-config class.
      *
      * @param target target type
-     * @return custom meta-data for the given type of the current entry
+     *
+     * @return custom metadata for the given type of this view-config
      */
     <T extends Annotation> List<T> getMetaData(Class<T> target);
 
     /**
-     * Callbacks which are configured for the entry and bound to the given meta-data type.
-     * @param metaDataType type of the meta-data (e.g. PageBean.class)
-     * @return descriptor for the callback or null if there is no callback-method
+     * Callbacks which are configured for this view-config and bound to the given metadata type.
+     *
+     * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
+     *
+     * @return descriptor for the callback or null if there is no callback method
      */
     CallbackDescriptor getCallbackDescriptor(Class<? extends Annotation> metaDataType);
 
     /**
-     * Callbacks which are configured for the entry and bound to the given meta-data type.
-     * @param metaDataType type of the meta-data (e.g. PageBean.class)
+     * Callbacks which are configured for this view-config and bound to the given metadata type.
+     *
+     * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
      * @param callbackType type of the callback (e.g. PreRenderView.class)
+     *
      * @return descriptor for the callback null if there is no callback-method
      */
     CallbackDescriptor getCallbackDescriptor(Class<? extends Annotation> metaDataType,
                                              Class<? extends Annotation> callbackType);
 
     /**
-     * Callbacks which are configured for the entry and bound to the given meta-data type.
-     * @param metaDataType type of the meta-data (e.g. PageBean.class)
-     * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor)
-     * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method
+     * Callbacks which are configured for this view-config and bound to the given metadata type.
+     *
+     * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
+     * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor)
+     *
+     * @return executable descriptor for the callback or null if there is no callback method
      */
     @SuppressWarnings("rawtypes")
     //TODO <T extends ExecutableCallbackDescriptor<?>> when major version is incremented
@@ -74,11 +83,13 @@ public interface ConfigDescriptor<CT /*config type*/>
                                                                                Class<? extends T> executorType);
 
     /**
-     * Callbacks which are configured for the entry and bound to the given meta-data type.
-     * @param metaDataType type of the meta-data (e.g. PageBean.class)
+     * Callbacks which are configured for this view-config and bound to the given metadata type.
+     *
+     * @param metaDataType type of the metadata (e.g. ViewControllerRef.class)
      * @param callbackType type of the callback (e.g. PreRenderView.class)
-     * @param executorType type of the executor which allows to get a typed result (e.g. Secured.Descriptor)
-     * @return descriptor for the callback which also allows to invoke it or null if there is no callback-method
+     * @param executorType type of the executor which returns a typed result (e.g. Secured.Descriptor)
+     *
+     * @return executable descriptor for the callback or null if there is no callback method
      */
     @SuppressWarnings("rawtypes")
     //TODO <T extends ExecutableCallbackDescriptor<?>> when major version is incremented
@@ -87,7 +98,8 @@ public interface ConfigDescriptor<CT /*config type*/>
                                                                                Class<? extends T> executorType);
 
     /**
-     * Returns the string representation of the resource represented by #getConfigClass
+     * Returns the string representation of the resource (page, folder) represented by this view-config.
+     *
      * @return relative path to the folder or page
      */
     String getPath();

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
index b4acf5a..34b794a 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/DefaultCallback.java
@@ -25,38 +25,44 @@ import java.lang.annotation.Target;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
-@Target( METHOD )
-@Retention(RUNTIME)
-@Documented
-
 /**
- * A ConfigDescriptor can contain CallbackDescriptors in general as well as ExecutableCallbackDescriptors.
- * An ExecutableCallbackDescriptor can reference one or multiple callback-method/s. If there is only one callback type,
- * it's possible to annotate it with @DefaultCallback.
- * That allows to handle it in an easier fashion
- * (= without providing a special marker (-annotation) for the target method).
+ * A ConfigDescriptor can contain CallbackDescriptors or ExecutableCallbackDescriptors. An ExecutableCallbackDescriptor
+ * can reference one or more callback method(s). If there is only one callback type, it's possible to annotate it with
+ * {@code @DefaultCallback}. That eliminates the need for a special marker annotation for the target method.
+ *
+ * If there are multiple callback types, it's necessary to use custom annotations as marker for the target method (e.g.
+ * see {@code @Secured} vs. {@code @ViewControllerRef}).
  *
- * If there are multiple callback types, it's needed to use custom annotations as marker for the target method.
- * (e.g. see @Secured vs. @ViewControllerBean)
+ * <pre>
+ * {@code
+ * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(SomePage.class);
  *
- * ViewConfigDescriptor viewConfigDescriptor = viewConfigResolver.getViewConfigDescriptor(PageConfig.class);
  * viewConfigDescriptor.getExecutableCallbackDescriptor(
  *   Secured.class, Secured.Descriptor.class).execute(accessDecisionVoterContext);
- * is short for
+ * }</pre> is short for
+ * <pre>
+ * {@code
  * viewConfigDescriptor.getExecutableCallbackDescriptor(
  *   Secured.class, DefaultCallback.class, Secured.Descriptor.class).execute(accessDecisionVoterContext);
+ * }</pre>
  *
  * whereas e.g.
+ * <pre>
+ * {@code
  * viewConfigDescriptor.getExecutableCallbackDescriptor(
- *   ViewControllerBean.class, PreRenderView.class, ViewControllerBean.ViewControllerDescriptor.class).execute();
- * or just
+ *   ViewControllerRef.class, PreRenderView.class, ViewControllerRef.Descriptor.class).execute();
+ * }</pre> or just
+ * <pre>
+ * {@code
  * viewConfigDescriptor.getExecutableCallbackDescriptor(
- * ViewControllerBean.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute();
- *
- * are needed to call only @PreRenderView callbacks
- * (and not the others like @InitView which are also bound to @ViewControllerBean)
+ *   ViewControllerRef.class, PreRenderView.class, SimpleCallbackDescriptor.class).execute();
+ * }</pre> are needed to call @PreRenderView callbacks specifically (instead of the others like @InitView which are also
+ * bound to @ViewControllerRef).
  */
 //TODO find a better name
-public @interface DefaultCallback
+@Target( METHOD )
+@Retention(RUNTIME)
+@Documented
+public @interface DefaultCallback 
 {
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
index 16c80b5..afa3bb5 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ExecutableCallbackDescriptor.java
@@ -26,9 +26,9 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Specialized {@link CallbackDescriptor}
- * which provides {@link #execute} only for concrete descriptors, but doesn't expose it (-> can't get used by accident).
- * Concrete implementations can provide type-safe versions of it, but delegate the final execution to {@link #execute}.
+ * Specialized {@link CallbackDescriptor} which provides {@link #execute} only for concrete descriptors, but doesn't
+ * expose it (and can't get used by accident). Concrete implementations can provide type-safe versions of it, but
+ * delegate the final execution to {@link #execute}.
  *
  * @param <R> return type
  */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
index 15e07ba..a157e5a 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/InlineViewMetaData.java
@@ -28,6 +28,17 @@ import java.lang.annotation.Target;
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Provides the ability to apply metadata to a view-config "remotely" &ndash; from a
+ * different place than the view-config itself (and with different syntax and a different annotation).
+ *
+ * <p>
+ * <b>For example</b>, the @ViewControllerRef (main) vs. @ViewRef (inline) &ndash; the @ViewControllerRef is applied
+ * directly on a view-config and references a view-controller, but there's also @ViewRef, which has the same purpose,
+ * but is applied in reverse &ndash; on a view-controller, referencing a view-config.
+ * </p>
+ */
+
 @Target({ ANNOTATION_TYPE })
 @Retention(RUNTIME)
 @Documented

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
index 81b828e..5d7ff6b 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SimpleCallbackDescriptor.java
@@ -22,8 +22,8 @@ import java.lang.annotation.Annotation;
 import java.util.List;
 
 /**
- * {@link ExecutableCallbackDescriptor} for simple callback-methods without (supported) parameters,
- * which exposes #execute without parameters.
+ * {@link ExecutableCallbackDescriptor} for simple callback methods without (supported) parameters, which exposes
+ * #execute without parameters.
  *
  * @param <R> return type
  */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
index acbf094..9e37d14 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/SkipMetaDataMerge.java
@@ -25,13 +25,13 @@ import java.lang.annotation.Target;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
+/**
+ * Disables metadata merging on attributes of @ViewMetaData annotations. Used in cases (e.g. @Folder#name) where it
+ * doesn't make sense to merge that part with inherited information.
+ */
 @Target( METHOD )
 @Retention(RUNTIME)
 @Documented
-
-/**
- * In some cases (e.g. @Folder#name) it doesn't make sense to merge that part with inherited information.
- */
 public @interface SkipMetaDataMerge
 {
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
index 7a937f8..0a2fe9f 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigDescriptor.java
@@ -21,17 +21,16 @@ package org.apache.deltaspike.core.api.config.view.metadata;
 import org.apache.deltaspike.core.api.config.view.ViewConfig;
 
 /**
- * Descriptor which represents a concrete view (/page).
+ * Descriptor which represents a concrete view (page).
  */
 public interface ViewConfigDescriptor extends ConfigDescriptor<ViewConfig>
 {
     /**
-     * View-ID of the current descriptor
-     * The default implementation returns the same as ConfigDescriptor#getPath.
-     * For the default implementation (and default integration with JSF) it's in place to provide a straightforward API.
+     * View ID of the current descriptor. The default implementation returns the same as ConfigDescriptor#getPath. For
+     * the default implementation (and default integration with JSF) it's in place to provide a straightforward API.
      * However, e.g. an integration for a different view technology can use it e.g. for a logical id.
      *
-     * @return current view-id
+     * @return current view ID
      */
     String getViewId();
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
index 82d2de7..514205c 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewConfigResolver.java
@@ -23,13 +23,13 @@ import org.apache.deltaspike.core.api.config.view.ViewConfig;
 import java.util.List;
 
 /**
- * Resolver for view-configs
+ * Resolver of view-configs.
  *
- * A {@link ConfigDescriptor} can be bound to any config-class (without required base-type).
- * That's needed e.g. for folder-configs. Whereas {@link ViewConfigDescriptor}s only represent config-classes which
- * inherit from {@link ViewConfig} which is required for all page-configs.
+ * A {@link ConfigDescriptor} can be bound to any config class (without required base type). That's needed e.g. for
+ * folder-configs. Whereas {@link ViewConfigDescriptor}s only represent classes which inherit from {@link ViewConfig}
+ * which is required for all view-configs.
  *
- * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to configure a custom resolver.
+ * Use {@link org.apache.deltaspike.core.spi.config.view.ViewConfigRoot} to register a custom resolver.
  */
 //TODO re-visit name since we also need ConfigDescriptor
 public interface ViewConfigResolver
@@ -37,48 +37,51 @@ public interface ViewConfigResolver
     ConfigDescriptor<?> getConfigDescriptor(String path);
 
     /**
-     * Resolves the {@link ConfigDescriptor} for the given config-class
+     * Resolves the {@link ConfigDescriptor} for the given class.
      *
-     * @param configClass config-class (which usually represents a folder node)
-     * @return config-descriptor which represents the given config-class
+     * @param configClass config class which usually represents a folder node
+     *
+     * @return config descriptor which represents the given config class
      */
     ConfigDescriptor<?> getConfigDescriptor(Class<?> configClass);
 
     //TODO re-visit name (depends on other discussions)
     /**
-     * Resolves all descriptors for folders
+     * Resolves all descriptors for folders.
      *
-     * @return all descriptors for the known view-configs
+     * @return all descriptors for the known folder-configs
      */
     List<ConfigDescriptor<?>> getConfigDescriptors();
 
     /**
-     * Resolves the {@link ViewConfigDescriptor} for the given view-id
+     * Resolves the {@link ViewConfigDescriptor} for the given view-id.
      *
      * @param viewId view-id of the page
-     * @return view-config-descriptor which represents the given view-id, null otherwise
+     *
+     * @return view-config descriptor which represents the given view-id, null otherwise
      */
     ViewConfigDescriptor getViewConfigDescriptor(String viewId);
 
     /**
-     * Resolves the {@link ViewConfigDescriptor} for the given view-config-class
+     * Resolves the {@link ViewConfigDescriptor} for the given view-config class.
+     *
+     * @param viewDefinitionClass view-config class of the page
      *
-     * @param viewDefinitionClass view-config-class of the page
-     * @return view-config-descriptor which represents the given view-config-class
+     * @return view-config descriptor which represents the given view-config class
      */
     ViewConfigDescriptor getViewConfigDescriptor(Class<? extends ViewConfig> viewDefinitionClass);
 
     /**
-     * Resolves all descriptors for the known {@link ViewConfig}s
+     * Resolves all descriptors for the known {@link ViewConfig}s.
      *
      * @return all descriptors for the known view-configs
      */
     List<ViewConfigDescriptor> getViewConfigDescriptors();
 
     /**
-     * Resolves the descriptor for the default-error page
+     * Resolves the descriptor for the default error page.
      *
-     * @return descriptor for the default-error page
+     * @return descriptor for the default error page
      */
     ViewConfigDescriptor getDefaultErrorViewConfigDescriptor();
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
index 095d5f8..a1f16c9 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/metadata/ViewMetaData.java
@@ -28,9 +28,11 @@ import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This meta-annotation allows to create custom meta-data which can be used for view-configs.
- * Per default meta-data of a lower level overrides meta-data on a higher level which has the same type.
- * Can be customized via annotating the final annotation as a whole via @Aggregated(true) or only special fields of it.
+ * Meta-annotation for custom metadata which can be applied to view-configs.
+ *
+ * By default, metadata of a lower level overrides metadata of the same type from a higher level (cascading behaviour).
+ * This behaviour can be changed by annotating the target annotation (or only chosen fields of it) with
+ * {@code @Aggregated(true)}.
  */
 @Target({ ANNOTATION_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/config/view/navigation/NavigationParameter.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
index 9b84ddf..fdecffc 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameter.java
@@ -32,8 +32,9 @@ import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This annotation can be used as interceptor for JSF action methods as an alternative for
- * {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext}.
+ * Used on JSF action methods, this adds navigation parameters (key-value pairs) to the resulting navigation string.
+ * Alternatively, {@link org.apache.deltaspike.core.api.config.view.navigation.NavigationParameterContext} can be used
+ * to add the parameters.
  */
 @Target({ METHOD, TYPE })
 @Retention(RUNTIME)
@@ -45,14 +46,14 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
 public @interface NavigationParameter
 {
     /**
-     * Key of the parameter
+     * Key of the parameter.
      *
      * @return name of the key
      */
     @Nonbinding String key();
 
     /**
-     * Value or EL-Expression of the parameter
+     * Value of the parameter, a plain String or an EL expression.
      *
      * @return ref or expression
      */
@@ -64,7 +65,7 @@ public @interface NavigationParameter
 
     //TODO add special support for list-annotations (add value automatically)
     /**
-     * Allows to specify multiple parameters (@see ViewParameter)
+     * A container for multiple NavigationParameters.
      */
     @ViewMetaData
     @Aggregated(true)
@@ -72,7 +73,7 @@ public @interface NavigationParameter
     public static @interface List
     {
         /**
-         * 1-n parameters
+         * One or more navigation parameters.
          *
          * @return parameters
          */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
index 207ad02..5efa3d0 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/NavigationParameterContext.java
@@ -22,7 +22,7 @@ import java.io.Serializable;
 import java.util.Map;
 
 /**
- * Can be used to add parameters dynamically to the final navigation string
+ * Can be used to add parameters dynamically to the final navigation string.
  */
 public interface NavigationParameterContext extends Serializable
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
index 80b8fd3..4c60eda 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/ViewNavigationHandler.java
@@ -21,14 +21,14 @@ package org.apache.deltaspike.core.api.config.view.navigation;
 import org.apache.deltaspike.core.api.config.view.ViewConfig;
 
 /**
- * Allows to trigger manual navigation via the type-safe {@link ViewConfig} approach.
+ * A type-safe {@link ViewConfig}-based NavigationHandler wrapper.
  */
 public interface ViewNavigationHandler
 {
     /**
      * Triggers navigation to the given view.
      *
-     * @param targetView the view which is the navigation target
+     * @param targetView the navigation target
      */
     void navigateTo(Class<? extends ViewConfig> targetView);
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
index 110cf61..c98af03 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/config/view/navigation/event/PreViewConfigNavigateEvent.java
@@ -21,8 +21,8 @@ package org.apache.deltaspike.core.api.config.view.navigation.event;
 import org.apache.deltaspike.core.api.config.view.ViewConfig;
 
 /**
- * Event will be fired before the navigation (from and to a view-config based page) occurs.
- * With {@link #navigateTo(Class)} it's possible to change the navigation target.
+ * This event is fired before a navigation from/to a view-config-based page occurs. With {@link #navigateTo(Class)} it's
+ * possible to change the navigation target.
  */
 public class PreViewConfigNavigateEvent
 {
@@ -30,7 +30,7 @@ public class PreViewConfigNavigateEvent
     private Class<? extends ViewConfig> toView;
 
     /**
-     * Constructor for creating the event for the given source and target view
+     * Constructor for creating the event for the given source and target view.
      *
      * @param fromView source-view
      * @param toView   target-view
@@ -62,7 +62,7 @@ public class PreViewConfigNavigateEvent
     }
 
     /**
-     * Allows to change the navigation target.
+     * Changes the navigation target.
      *
      * @param toView new navigation target
      */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
index 8e7078a..707d457 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/BeforeHandles.java
@@ -27,10 +27,15 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE
- * traversal of the exception chain. Handlers are typically in the form of
- * <code>public void ... (@BeforeHandles ... CaughtException<...> ...)</code> methods.
- * If a method has a return type, it is ignored.
+ * Marker annotation for a method to be considered an Exception Handler, handles the exception in the BEFORE traversal
+ * of the exception chain.
+ * <p>
+ * Handlers methods typically have this form:<br />
+ * <pre>public void handle(@BeforeHandles <i>@OptionalQualifier</i> ExceptionEvent&lt;<i>TypeOfTheException</i>&gt; evt)
+ * </pre>.
+ * </p>
+ *
+ * If a handler method has a return type, it is ignored.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
@@ -38,7 +43,8 @@ import java.lang.annotation.Target;
 public @interface BeforeHandles
 {
     /**
-     * Precedence relative to callbacks for the same type
+     * Precedence relative to callbacks for the same type. Handler with a higher ordinal is invoked before a handler
+     * with a lower ordinal.
      */
     int ordinal() default 0;
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
index d706909..83a3e2f 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandler.java
@@ -27,6 +27,9 @@ import java.lang.annotation.Target;
 
 /**
  * Marker for types containing Exception Handler methods.
+ *
+ * @see BeforeHandles
+ * @see Handles
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
index e454e86..eef759d 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/ExceptionHandlingFlow.java
@@ -20,7 +20,7 @@
 package org.apache.deltaspike.core.api.exception.control;
 
 /**
- * Flow control enum.  Used in the dispatcher to determine how to markHandled.
+ * Enum of exception handling states. Used in the dispatcher to determine how to markHandled.
  */
 public enum ExceptionHandlingFlow
 {

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
index d875b05..22d7c14 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/HandlerMethod.java
@@ -27,7 +27,7 @@ import java.lang.reflect.Type;
 import java.util.Set;
 
 /**
- * Meta data interface about an exception handler. It is the responsibility of the
+ * Metadata interface for an exception handler method. It is the responsibility of the
  * implementation to support {@link javax.enterprise.inject.spi.InjectionPoint}s and to
  * validate those {@link javax.enterprise.inject.spi.InjectionPoint}s.
  *
@@ -59,7 +59,8 @@ public interface HandlerMethod<T extends Throwable>
     void notify(ExceptionEvent<T> event, BeanManager beanManager) throws Exception;
 
     /**
-     * Obtains the precedence of the handler, relative to other handlers for the same type.
+     * Obtains the precedence of the handler, relative to other handlers for the same type. Handler with a higher
+     * ordinal is invoked before a handler with a lower ordinal.
      */
     int getOrdinal();
 

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
index 8d86160..d915bfc 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/Handles.java
@@ -26,9 +26,15 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Marker annotation for a method to be considered an Exception Handler. Handlers are typically in the form of
- * <code>public void ... (@Handles ... CaughtException<...> ...)</code> methods. If a method has a return type, it is
- * ignored.
+ * Marker annotation for a method to be considered an Exception Handler.
+ *
+ * <p>
+ * Handlers typically have this form:
+ * <pre>
+ * public void handle(@Handles <i>@OptionalQualifier</i> ExceptionEvent&lt;<i>TypeOfTheException</i>&gt; evt)</pre>
+ * </p>
+ *
+ * If a handler method has a return type, it is ignored.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.PARAMETER)
@@ -36,7 +42,8 @@ import java.lang.annotation.Target;
 public @interface Handles
 {
     /**
-     * Precedence relative to handlers for the same type
+     * Precedence relative to handlers for the same type. Handler with a higher ordinal is invoked before a handler with
+     * a lower ordinal.
      */
     int ordinal() default 0; //TODO discuss Precedence
 }

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
index c4a2402..42a6b60 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionEvent.java
@@ -20,8 +20,8 @@
 package org.apache.deltaspike.core.api.exception.control.event;
 
 /**
- * Payload for an exception to be handled.  Implementations of this interface should not expose internals and remain
- * immutable for this contract.
+ * Payload for an exception to be handled. Implementations of this interface should not expose internals and should
+ * remain immutable.
  *
  * @param <T> Exception type this event represents
  */

http://git-wip-us.apache.org/repos/asf/deltaspike/blob/34b713b4/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
----------------------------------------------------------------------
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
index c134645..18b8fe6 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/exception/control/event/ExceptionToCatchEvent.java
@@ -27,7 +27,7 @@ import java.util.HashSet;
 import java.util.Set;
 
 /**
- * Entry point event into the Catch system.  This object is nearly immutable, the only mutable portion
+ * Entry point event into the Exception Control system.  This object is nearly immutable, the only mutable portion
  * is the handled flag.
  */
 @SuppressWarnings("CdiManagedBeanInconsistencyInspection")
@@ -84,9 +84,10 @@ public class ExceptionToCatchEvent implements Serializable
     }
 
     /**
-     * Test to see if the exception has been handled via Solder Catch.
+     * Test to see if the exception has already been processed by an
+     * {@link org.apache.deltaspike.core.api.exception.control.ExceptionHandler}.
      *
-     * @return test if the exception has been through Solder Catch handling.
+     * @return true if the exception has already been processed by a handler; false otherwise
      */
     public boolean isHandled()
     {


Mime
View raw message