Clarify rules and guarantees around property name sets

Fixes eclipse#431

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

@@ -130,8 +130,25 @@ public interface Config {
     <T> Optional<T> getOptionalValue(String propertyName, Class<T> propertyType);
 
     /**
-     * Return all property names returned by any of the underlying {@linkplain ConfigSource configuration sources}.
-     * The order of the returned property names is unspecified.
+     * Returns a sequence of configuration property names. The order of the returned property names is unspecified.
+     * <p>
+     * The returned property names are unique; that is, if a name is returned once by a given iteration, it will not be
+     * returned again during that same iteration.
+     * <p>
+     * There is no guarantee about the completeness or currency of the names returned, nor is there any guarantee that a
+     * name that is returned by the iterator will resolve to a non-empty value or be found in any configuration source
+     * associated with the configuration; for example, it is allowed for this method to return an empty set always.
+     * However, the implementation <em>should</em> return a set of names that is useful to a
+     * user that wishes to browse the configuration.
+     * <p>
+     * It is implementation-defined whether the returned names reflect a point-in-time "snapshot" of names, or an
+     * aggregation of multiple point-in-time "snapshots", or a more dynamic view of the available property names.
+     * Implementations are not required to return the same sequence of names on each iteration; however, the produced
+     * {@link java.util.Iterator Iterator} must adhere to the contract of that class, and must not return any more
+     * elements once its {@link java.util.Iterator#hasNext() hasNext()} method returns {@code false}.
+     * <p>
+     * The returned instance is thread safe and may be iterated concurrently.  The individual iterators are not
+     * thread-safe.
      *
      * @return the names of all configured keys of the underlying configuration.
      */

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

@@ -54,7 +54,7 @@
  * <ol>
  * <li>{@linkplain System#getProperties() System properties}, with an {@linkplain #getOrdinal() ordinal value} of {@code 400}</li>
  * <li>{@linkplain System#getenv() Environment properties}, with an ordinal value of {@code 300}</li>
- * <li>The {@code /META-INF/microprofile-config.properties} {@linkplain ClassLoader#getResource(String) resource}, 
+ * <li>The {@code /META-INF/microprofile-config.properties} {@linkplain ClassLoader#getResource(String) resource},
  * with an ordinal value of {@code 100}</li>
  * </ol>
  *
@@ -124,6 +124,13 @@ default Map<String, String> getProperties() {
      * Implementations should consider replacing this with a more performant implementation.
      * <p>
      * The returned property names may be a subset of the names of the total set of retrievable properties in this config source.
+     * <p>
+     * The returned set is not required to allow concurrent or multi-threaded iteration; however, if the same set is
+     * returned by multiple calls to this method, then the implementation must support concurrent and multi-threaded
+     * iteration of that set.
+     * <p>
+     * The set of keys returned <em>may</em> be a point-in-time snapshot, or <em>may</em> change over time (even
+     * during active iteration) to reflect dynamic changes to the available set of keys.
      *
      * @return a set of property names that are known to this configuration source
      */