Major JavaDoc cleanups, including grammar, structure, style, and cont…

…ent improvements.

This works towards eclipse#447 and also will make it easier to specify eclipse#448, eclipse#426, etc.

api/src/main/java/org/eclipse/microprofile/config/Config.java

@@ -89,48 +89,59 @@ public interface Config {
 
  /**
  * Return the resolved property value with the specified type for the
- * specified property name from the underlying {@link ConfigSource ConfigSources}.
- *
- * If this method gets used very often then consider to locally store the configured value.
+ * specified property name from the underlying {@linkplain ConfigSource configuration sources}.
+ * <p>
+ * The configuration value is not guaranteed to be cached by the implementation, and may be expensive
+ * to compute; therefore, if the returned value is intended to be frequently used, callers should consider storing
+ * rather than recomputing it.
  *
  * @param <T>
  * The property type
  * @param propertyName
- * The configuration propertyName.
+ * The configuration property name
  * @param propertyType
- * The type into which the resolve property value should get converted
- * @return the resolved property value as an object of the requested type.
- * @throws java.lang.IllegalArgumentException if the property cannot be converted to the specified type.
- * @throws java.util.NoSuchElementException if the property isn't present in the configuration.
+ * The type into which the resolved property value should get converted
+ * @return the resolved property value as an instance of the requested type
+ * @throws java.lang.IllegalArgumentException if the property cannot be converted to the specified type
+ * @throws java.util.NoSuchElementException if the property isn't present in the configuration
  */
  <T> T getValue(String propertyName, Class<T> propertyType);
 
  /**
  * Return the resolved property value with the specified type for the
- * specified property name from the underlying {@link ConfigSource ConfigSources}.
+ * specified property name from the underlying {@linkplain ConfigSource configuration sources}.
+ * <p>
+ * The configuration value is not guaranteed to be cached by the implementation, and may be expensive
+ * to compute; therefore, if the returned value is intended to be frequently used, callers should consider storing
+ * rather than recomputing it.
  *
  * If this method is used very often then consider to locally store the configured value.
  *
  * @param <T>
  * The property type
  * @param propertyName
- * The configuration propertyName.
+ * The configuration property name
  * @param propertyType
- * The type into which the resolve property value should be converted
- * @return The resolved property value as an Optional of the requested type.
+ * The type into which the resolved property value should be converted
+ * @return The resolved property value as an {@code Optional} wrapping the requested type
  *
- * @throws java.lang.IllegalArgumentException if the property cannot be converted to the specified type.
+ * @throws java.lang.IllegalArgumentException if the property cannot be converted to the specified type
  */
  <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);
 
  /**
- * Return all property names used in any of the underlying {@link ConfigSource ConfigSources}.
+ * Return all property names returned by any of the underlying {@linkplain ConfigSource configuration sources}.
+ * The order of the returned property names is unspecified.
+ *
  * @return the names of all configured keys of the underlying configuration.
  */
  Iterable<String> getPropertyNames();
 
  /**
- * @return all currently registered {@link ConfigSource ConfigSources} sorted by descending ordinal and ConfigSource name
+ * Return all of the currently registered {@linkplain ConfigSource configuration sources} for this configuration.
+ * The returned sources will be sorted by descending ordinal value and name.
+ *
+ * @return the configuration sources
  */
  Iterable<ConfigSource> getConfigSources();
 }

api/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java

@@ -36,33 +36,34 @@
 /**
  * <p>
  * This is the central class to access a {@link Config}.
- * A {@link Config} provides access to application Configuration.
- * That might be auto-discovered {@code Config} or even manually created one.
+ * A {@link Config} provides access to the application's configuration.
+ * It may have been automatically discovered, or manually created and registered.
  *
  * <p>
  * The default usage is to use {@link #getConfig()} to automatically pick up the
- * 'Configuration' for the Thread Context ClassLoader (See
- * {@link Thread#getContextClassLoader()}).
+ * <em>configuration</em> for the current thread's {@linkplain Thread#getContextClassLoader() context class loader}.
  *
  * <p>
- * A 'Configuration' consists of the information collected from the registered {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources}.
- * These {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} get sorted according to
- * their <em>ordinal</em> defined via {@link org.eclipse.microprofile.config.spi.ConfigSource#getOrdinal()}.
- * Thus it is possible to overwrite configuration by providing in a ConfigSource with higher importance from outside.
+ * A <em>configuration</em> consists of information collected from the registered
+ * <em>{@linkplain org.eclipse.microprofile.config.spi.ConfigSource configuration sources}</em>, combined with the set of
+ * registered {@linkplain org.eclipse.microprofile.config.spi.Converter converters}.
+ * The <em>configuration sources</em> get sorted according to their
+ * <em>{@linkplain org.eclipse.microprofile.config.spi.ConfigSource#getOrdinal() ordinal value}</em>.
+ * Thus it is possible to override a lower-priority <em>configuration source</em> with a higher-priority one.
  *
  * <p>
- * It is also possible to register custom {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} to flexibly
- * extend the configuration mechanism. An example would be to pick up
+ * It is also possible to register custom <em>configuration sources</em> to flexibly
+ * extend the configuration mechanism. For example, a configuration source could be provided which reads
  * configuration values from a database table.
- *
+ * <p>
  * Example usage:
  *
  * <pre>
  * String restUrl = ConfigProvider.getConfig().getValue(&quot;myproject.some.remote.service.url&quot;, String.class);
  * Integer port = ConfigProvider.getConfig().getValue(&quot;myproject.some.remote.service.port&quot;, Integer.class);
  * </pre>
  *
- * For more advanced use cases like e.g. registering a manually created {@link Config} please see
+ * For more advanced use cases (e.g. registering a manually created {@link Config} instance), please see
  * {@link ConfigProviderResolver#registerConfig(Config, ClassLoader)} and {@link ConfigProviderResolver#getBuilder()}.
  *
  * @author <a href="mailto:struberg@apache.org">Mark Struberg</a>
@@ -76,30 +77,29 @@ private ConfigProvider() {
  }
 
  /**
- * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} of the
- * current Thread Context ClassLoader (TCCL)
- * 
+ * Get the {@linkplain Config configuration} corresponding to the current application, as defined by the
+ * calling thread's {@linkplain Thread#getContextClassLoader() context class loader}.
  * <p>
- * 
- * The {@link Config} will be stored for future retrieval.
+ * The {@link Config} instance will be created and registered to the context class loader if no such configuration
+ * is already created and registered.
  * <p>
- * There is exactly a single Config instance per ClassLoader
+ * Each class loader corresponds to exactly one configuration.
  *
- * @return the config object for the thread context classloader
+ * @return the configuration instance for the thread context class loader
  */
  public static Config getConfig() {
  return ConfigProviderResolver.instance().getConfig();
  }
 
  /**
- * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} of the
- * specified ClassLoader
- *
+ * Get the {@linkplain Config configuration} for the application corresponding to the given class loader instance.
+ * <p>
+ * The {@link Config} instance will be created and registered to the given class loader if no such configuration
+ * is already created and registered.
  * <p>
- * There is exactly a single Config instance per ClassLoader
+ * Each class loader corresponds to exactly one configuration.
  *
- * @param cl the specified classloader
- * @return the config for the specified classloader
+ * @return the configuration instance for the given class loader
  */
  public static Config getConfig(ClassLoader cl) {
  return ConfigProviderResolver.instance().getConfig(cl);

api/src/main/java/org/eclipse/microprofile/config/package-info.java

@@ -21,7 +21,7 @@
 /**
  * <p>Configuration for Java Microprofile
  *
- * <h2>Rational</h2>
+ * <h2>Rationale</h2>
  *
  * <p>For many project artifacts (e.g. WAR, EAR) it should be possible to build them only once
  * and then install them at different customers, stages, etc.
@@ -72,7 +72,7 @@
  *
  * @author <a href="emijiang@uk.ibm.com">Emily Jiang</a>
  * @author <a href="mailto:struberg@apache.org">Mark Struberg</a>
- * 
+ *
  */
 
 @org.osgi.annotation.versioning.Version("1.0.1")

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

@@ -31,7 +31,7 @@
 import org.eclipse.microprofile.config.Config;
 
 /**
- * Builder for manually creating an instance of a {@code Config}.
+ * A builder for manually creating a configuration instance.
  *
  * @see ConfigProviderResolver#getBuilder()
  *
@@ -42,77 +42,83 @@
 @org.osgi.annotation.versioning.ProviderType
 public interface ConfigBuilder {
  /**
- * Add the default config sources appearing on the builder's classpath
- * including:
- * <ol>
- * <li>System properties</li>
- * <li>Environment properties</li>
- * <li>/META-INF/microprofile-config.properties</li>
- * </ol>
+ * Add the <a href="ConfigSource.html#default_config_sources"><em>default configuration sources</em></a>
+ * to the configuration being built.
  *
- * @return the ConfigBuilder with the default config sources
+ * @return this configuration builder instance
  */
  ConfigBuilder addDefaultSources();
 
  /**
- * Add the config sources appearing to be loaded via service loader pattern
+ * Add the all configuration sources which can be <a href="ConfigSource.html#discovery">discovered</a> from
+ * this configuration builder's {@linkplain #forClassLoader(ClassLoader) class loader}.
  *
- * @return the ConfigBuilder with the autodiscovered config sources
+ * @return this configuration builder instance
  */
  ConfigBuilder addDiscoveredSources();
 
  /**
- * Add the converters to be loaded via service loader pattern
+ * Add the all configuration converters which can be <a href="Converter.html#discovery">discovered</a> from
+ * this configuration builder's {@linkplain #forClassLoader(ClassLoader) class loader}.
  *
- * @return the ConfigBuilder with the autodiscovered converters
+ * @return this configuration builder instance
  */
  ConfigBuilder addDiscoveredConverters();
+
  /**
- * Return the ConfigBuilder for a given classloader
+ * Specify the class loader for which this configuration is being built.
  *
- * @param loader the specified classloader
- * @return the ConfigureBuilder for the given classloader
+ * @param loader the class loader
+ * @return this configuration builder instance
  */
  ConfigBuilder forClassLoader(ClassLoader loader);
 
  /**
- * Add the specified {@link ConfigSource}.
+ * Add the specified {@link ConfigSource} instances to the configuration being built.
  *
- * @param sources the config sources
- * @return the ConfigBuilder with the configured sources
+ * @param sources the configuration sources
+ * @return this configuration builder instance
  */
  ConfigBuilder withSources(ConfigSource... sources);
 
  /**
- * Add the specified {@link Converter}.
- * This method uses reflection to determine what type the converter is for.
- * When using lambda expressions for custom converters you should use
- * {@link #withConverter(Class, int, Converter)} and pass the target type explicitly
- * as lambda expressions do not offer enough type information to the reflection API.
+ * Add the specified {@link Converter} instances to the configuration being built.
+ * <p>
+ * The implementation may use reflection to determine the target type of the converter. If the
+ * type cannot be determined reflectively, this method may fail with a runtime exception.
+ * <p>
+ * When using lambda expressions for custom converters you should use the
+ * {@link #withConverter(Class, int, Converter)} method and pass the target type explicitly,
+ * since lambda expressions generally do not offer enough type information to the reflection API
+ * in order to determine the target converter type.
+ * <p>
+ * The added converters will be given a priority of {@code 100}.
  *
- * @param converters the converters
- * @return the ConfigBuilder with the added converters
+ * @param converters the converters to add
+ * @return this configuration builder instance
  */
  ConfigBuilder withConverters(Converter<?>... converters);
 
-
  /**
- * Add the specified {@link Converter} for the given type.
- * This method does not rely on reflection to determine what type the converter is for
- * therefore also lambda expressions can be used.
+ * Add the specified {@link Converter} instance for the given type to the configuration being built.
+ * <p>
+ * 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}.
  *
- * @param type the Class of type to convert
- * @param priority the priority of the converter (custom converters have a default priority of 100).
+ * @param type the class of the type to convert
+ * @param priority the priority of the converter
  * @param converter the converter (can not be {@code null})
  * @param <T> the type to convert
- * @return the ConfigBuilder with the added converters
+ * @return this configuration builder instance
  */
  <T> ConfigBuilder withConverter(Class<T> type, int priority, Converter<T> converter);
 
  /**
- * Build the {@link Config} object.
+ * Build a new {@link Config} instance based on this builder instance.
  *
- * @return the Config object
+ * @return the new configuration object
  */
  Config build();
 }