Clarify Javadocs for SettingsLoaderFactory

core/src/main/java/org/elasticsearch/common/settings/loader/SettingsLoaderFactory.java

@@ -20,19 +20,28 @@
 package org.elasticsearch.common.settings.loader;
 
 /**
- * A settings loader factory automatically trying to identify what type of
+ * A class holding factory methods for settings loaders that attempts
- * {@link SettingsLoader} to use.
+ * to infer the type of the underlying settings content.
- *
- *
  */
 public final class SettingsLoaderFactory {
 
     private SettingsLoaderFactory() {
-
     }
 
     /**
-     * Returns a {@link SettingsLoader} based on the resource name.
+     * Returns a {@link SettingsLoader} based on the source resource
+     * name. This factory method assumes that if the resource name ends
+     * with ".json" then the content should be parsed as JSON, else if
+     * the resource name ends with ".yml" or ".yaml" then the content
+     * should be parsed as YAML, else if the resource name ends with
+     * ".properties" then the content should be parsed as properties,
+     * otherwise default to attempting to parse as JSON. Note that the
+     * parsers returned by this method will not accept null-valued
+     * keys.
+     *
+     * @param resourceName The resource name containing the settings
+     *                     content.
+     * @return A settings loader.
      */
     public static SettingsLoader loaderFromResource(String resourceName) {
         if (resourceName.endsWith(".json")) {
@@ -48,7 +57,17 @@ public final class SettingsLoaderFactory {
     }
 
     /**
-     * Returns a {@link SettingsLoader} based on the actual settings source.
+     * Returns a {@link SettingsLoader} based on the source content.
+     * This factory method assumes that if the underlying content
+     * contains an opening and closing brace ('{' and '}') then the
+     * content should be parsed as JSON, else if the underlying content
+     * fails this condition but contains a ':' then the content should
+     * be parsed as YAML, and otherwise should be parsed as properties.
+     * Note that the JSON and YAML parsers returned by this method will
+     * accept null-valued keys.
+     *
+     * @param source The underlying settings content.
+     * @return A settings loader.
      */
     public static SettingsLoader loaderFromSource(String source) {
         if (source.indexOf('{') != -1 && source.indexOf('}') != -1) {
@@ -59,4 +78,5 @@ public final class SettingsLoaderFactory {
         }
         return new PropertiesSettingsLoader();
     }
+
 }