Merge pull request #511 from kenfinnigan/javadoc-tweaks

Followup Javadoc fixes

api/src/main/java/org/eclipse/microprofile/config/spi/ConfigBuilder.java

@@ -50,15 +50,15 @@ public interface ConfigBuilder {
     ConfigBuilder addDefaultSources();
 
     /**
-     * Add the all configuration sources which can be <a href="ConfigSource.html#discovery">discovered</a> from
+     * Add all configuration sources which can be <a href="ConfigSource.html#discovery">discovered</a> from
      * this configuration builder's {@linkplain #forClassLoader(ClassLoader) class loader}.
      *
      * @return this configuration builder instance
      */
     ConfigBuilder addDiscoveredSources();
 
     /**
-     * Add the all configuration converters which can be <a href="Converter.html#discovery">discovered</a> from
+     * Add all configuration converters which can be <a href="Converter.html#discovery">discovered</a> from
      * this configuration builder's {@linkplain #forClassLoader(ClassLoader) class loader}.
      *
      * @return this configuration builder instance
@@ -105,7 +105,7 @@ public interface ConfigBuilder {
      * This method does not rely on reflection to determine the target type of the converter;
      * therefore, lambda expressions may be used for the converter instance.
      * <p>
-     * The priority value of custom converters is normally {@code 100}.
+     * The priority value of custom converters defaults to {@code 100} if not specified.
      *
      * @param type the class of the type to convert
      * @param priority the priority of the converter

api/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java

@@ -94,7 +94,7 @@
  */
 public interface ConfigSource {
     /**
-     * The name of the default configuration ordinal property, "{@code config_ordinal}".
+     * The name of the configuration ordinal property, "{@code config_ordinal}".
      */
     String CONFIG_ORDINAL = "config_ordinal";
 

spec/src/main/asciidoc/configprovider.asciidoc

@@ -31,7 +31,7 @@ There are 4 different ways to create a `Config` instance:
 * In CDI managed components, a user can use `@Inject` to access the current application configuration.
   The default and the auto discovered <<configsource,ConfigSources>> will be gathered to form a configuration.
   The default and the auto discovered <<converters,Converters>> will be gathered to form a configuration.
-  Injected instance of `Config` should behave the same as the one retrieved by `ConfigProvider.getConfig()`. 
+  Injected instance of `Config` should behave the same as the one retrieved by `ConfigProvider.getConfig()`.
   Injected config property values should be the same as if retrieved from an injected `Config` instance via `Config.getValue()`.
 
 * A factory method `ConfigProvider#getConfig()` to create a `Config` object based on automatically picked up `ConfigSources`
@@ -50,13 +50,31 @@ There are 4 different ways to create a `Config` instance:
 The builder has no config sources. Only the default converters are added. The `ConfigBuilder` object can be filled manually via methods like `ConfigBuilder#withSources(ConfigSources... sources)`.
    This configuration instance will by default not be shared by the `ConfigProvider`.
   This method is intended be used if a IoC container or any other external Factory can be used to give access to a manually created shared `Config`.
+** Create a builder:
++
+```
+ConfigProviderResolver resolver = ConfigProviderResolver.instance();
+ConfigBuilder builder = resolver.getBuilder();
+```
+** Add config sources and build:
++
+```
+Config config = builder.addDefaultSources().withSources(mySource).withConverters(myConverter).build;
+```
+** (optional) Manage the lifecycle of the config
++
+```
+resolver.registerConfig(config, classloader);
+resolver.releaseConfig(config);
+```
+
 
 The `Config` object created via builder pattern can be managed as follows:
 
 * A factory method `ConfigProviderResolver#registerConfig(Config config, ClassLoader classloader)` can be used to register a `Config` within the application.
   This configuration instance *will* be shared by `ConfigProvider#getConfig()`.
   Any subsequent call to `ConfigProvider#getConfig()` will return the registered `Config` instance for this application.
-  
+
 * A factory method `ConfigProviderResolver#releaseConfig(Config config)` to release the `Config` instance. This will unbind the current `Config` from the application.
 The <<configsource, ConfigSources>> that implement the `java.io.Closeable` interface will be properly destroyed.
 The <<converter, Converters>> that implement the `java.io.Closeable` interface will be properly destroyed.
@@ -66,8 +84,8 @@ All methods in the `ConfigProvider`, `ConfigProviderResolver` and `Config` imple
 
 The `Config` instances created via CDI are `Serializable`.
 
-If a `Config` instance is created via `@Inject Config` or `ConfigProvider#getConfig()` or via the builder pattern but later called `ConfigProviderResolver#registerConfig(Config config, Classloader classloader)`, the `Config` instance will be released when the application is closed. 
+If a `Config` instance is created via `@Inject Config` or `ConfigProvider#getConfig()` or via the builder pattern but later called `ConfigProviderResolver#registerConfig(Config config, Classloader classloader)`, the `Config` instance will be released when the application is closed.
 
 
 
-<<<
+<<<