Revised Environment and UI docs. Updated overall docs consistency.

addon-manager/README.asciidoc

@@ -66,6 +66,7 @@ and removal of addons programatically.
 [source,java]
 ----
 @Inject private AddonManager manager;
+...
 InstallRequest request = manager.install(AddonId.from("org.example:example", "0.0.1-SNAPSHOT"));
 request.perform();
 ----
@@ -76,7 +77,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<AddonManager> imported = addonRegistry.getServices(AddonManager.class);
+AddonRegistry registry = ...
+Imported<AddonManager> imported = registry.getServices(AddonManager.class);
 AddonManager manager = imported.get();
 ----
 ==== 

convert/README.asciidoc

@@ -44,7 +44,7 @@ converters, the factory will select the most appropriate converter type for the
 ----
 @Inject 
 private ConverterFactory factory;
-
+...
 Converter<String, Integer> converter = factory.create(String.class, Integer.class);
 ----
 +
@@ -54,7 +54,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<ConverterFactory> imported = addonRegistry.getServices(ConverterFactory.class);
+AddonRegistry registry = ...
+Imported<ConverterFactory> imported = registry.getServices(ConverterFactory.class);
 ConverterFactory factory = imported.get();
 ----
 

dependencies/README.asciidoc

@@ -51,7 +51,7 @@ capable of handling the given `DependencyQuery`.
 ----
 @Inject 
 private DependencyResolver resolver;
-
+...
 Set<Dependency> dependencies = resolver.resolveDependencies(...);
 DependencyMetadata metadata = resolver.resolveDependencyMetadata(...);
 ----
@@ -62,7 +62,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<DependencyResolver> imported = addonRegistry.getServices(DependencyResolver.class);
+AddonRegistry registry = ...
+Imported<DependencyResolver> imported = registry.getServices(DependencyResolver.class);
 for(ExportedInstance<DependencyResolver> instance : imported)
 {
    DependencyResolver resolver = instance.get();

environment/README.asciidoc

@@ -1,9 +1,11 @@
 == environment
 :idprefix: id_ 
 
-(choose one)
-This addon provides a *service environment* support for dependent addons.
-
+This addon *exports services* for use in other addons. The environment addon creates a non-persistent (in-memory)
+system where runtime configuration variables can be accessed in a safer, more type-safe setting. Because environment
+settings are non-persistent, they will only remain configured for as long as the application is running, or until
+they are changed or removed.
+
 === Dependencies: None
 
 == Setup
@@ -16,34 +18,52 @@ To use this addon, you must add it as a dependency in the *pom.xml* of your `for
 
 [source,xml]
 ----
-      <dependency>
-         <groupId>org.jboss.forge.addon</groupId>
-         <artifactId>environment</artifactId>
-         <classifier>forge-addon</classifier>
-         <version>${version}</version>
-      </dependency>
+<dependency>
+   <groupId>org.jboss.forge.addon</groupId>
+   <artifactId>environment</artifactId>
+   <classifier>forge-addon</classifier>
+   <version>${version}</version>
+</dependency>
 ----
 
 == Features
 
-Access the Environment service:: Environment properties are grouped by Category specializations. Category is a marker interface for exclusive use in the Environment addon.
-
+Environment service to provide global type-safe settings::
+ Environment properties are grouped by category specializations, and can be accessed by any consumer with knowledge of
+the proper interface types. Environment lookup will return the underlying configuration map for the given `Category` type.
++
 [source,java]
 ----
-@Inject Environment environment;
-
+@Inject private Environment environment;
 ...
-// Retrieves the properties configured for this specific category
-Map<Object, Object> userInterfaceProperties = environment.get(UserInterfaceCategory.class);
+Map<Object, Object> properties = environment.get(SomeCategory.class);
 ----
++
+[TIP] 
+====
+If your addon uses a container that does not support "@Inject" annotations, services such as the `Environment` may also be 
+accessed via the `AddonRegistry`:
 
+----
+AddonRegistry registry = ...
+Imported<Environment> imported = registry.getServices(Environment.class);
+Environment factory = imported.get();
+----
+==== 
 
-Where UserInterfaceCategory is a specialized marker interface with no methods:
-
+Custom environment categories::
+ It is possible to implement custom categories simply be extending the `Category` interface, where `Category` is a 
+specialized marker interface with no methods:
++
 [source,java]
 ----
-public interface UserInterfaceCategory extends Category
-{
-
+public interface MyCustomCategory extends Category {
 }
 ----
++
+Once your category has been created, it may be accessed via the `Environment` service.
+
+
+Consistent programming experience::
+ Because the Environment API provides an abstract model for handling non-persistent configuration, it is used in a
+ number of addons and should be considered the standard approach for runtime configuration.

facets/README.asciidoc

@@ -76,7 +76,7 @@ handles the installation of facets directly.
 ----
 @Inject
 private FacetFactory factory;
-
+...
 FacetedObject faceted = new FacetedObject();
 MyFacet facet = factory.install(faceted, MyFacet.class);
 ---- 
@@ -87,7 +87,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<FacetFactory> imported = addonRegistry.getServices(FacetFactory.class);
+AddonRegistry registry = ...
+Imported<FacetFactory> imported = registry.getServices(FacetFactory.class);
 FacetFactory factory = imported.get();
 ----
 ==== 

parser-java/README.asciidoc

@@ -56,7 +56,7 @@ The JavaSourceFactory allows for parsing and generation of Java sources via a ty
 ----
 @Inject 
 private JavaSourceFactory factory;
-
+...
 JavaClass myClass = factory.parse(JavaClass.class, "public class MyClass{}");
 ----
 +
@@ -66,7 +66,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<JavaSourceFactory> imported = addonRegistry.getServices(JavaSourceFactory.class);
+AddonRegistry registry = ...
+Imported<JavaSourceFactory> imported = registry.getServices(JavaSourceFactory.class);
 JavaSourceFactory factory = imported.get();
 ----
 ==== 

resources/README.asciidoc

@@ -64,7 +64,7 @@ real or virtual resource.
 ----
 @Inject 
 private ResourceFactory factory;
-
+...
 Resource<?> resource = factory.create(...);
 ----
 +
@@ -74,7 +74,8 @@ If your addon uses a container that does not support "@Inject" annotations, serv
 accessed via the `AddonRegistry`:
 
 ----
-Imported<ResourceFactory> imported = addonRegistry.getServices(ResourceFactory.class);
+AddonRegistry registry = ...
+Imported<ResourceFactory> imported = registry.getServices(ResourceFactory.class);
 ResourceFactory factory = imported.get();
 ----
 ====