Fix all the javadoc warnings

For broken doc comments in impl, just deleted them for
the most part rather than writing a bunch of useless docs.
"impl" is now included in the docs because javadoc 8 seems
to explode otherwise, but it's well-labeled as internal ABI.

config/build.sbt

@@ -39,6 +39,7 @@ javacOptions in (Compile, compile) ++= Seq("-source", "1.6", "-target", "1.8", "
 // we have to run tests in serial.
 parallelExecution in Test := false
 
-sources in (Compile, doc) ~= (_.filter(_.getParentFile.getName != "impl"))
+javacOptions in doc ++= Seq("-group", "Public API", "com.typesafe.config",
+                            "-group", "Internal Implementation - Not ABI Stable", "com.typesafe.config.impl")
 
 javaVersionPrefix in javaVersionCheck := Some("1.8")

config/src/main/java/com/typesafe/config/Config.java

@@ -756,11 +756,15 @@ public interface Config extends ConfigMergeable {
 
     /**
      * @deprecated  As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)}
+     * @param path the path
+     * @return list of millisecond values
      */
     @Deprecated List<Long> getMillisecondsList(String path);
 
     /**
      * @deprecated  As of release 1.1, replaced by {@link #getDurationList(String, TimeUnit)}
+     * @param path the path
+     * @return list of nanosecond values
      */
     @Deprecated List<Long> getNanosecondsList(String path);
 

config/src/main/java/com/typesafe/config/ConfigException.java

@@ -322,7 +322,10 @@ public abstract class ConfigException extends RuntimeException implements Serial
             this.problem = problem;
         }
 
-        /** Returns the config setting causing the problem. */
+        /**
+         * Returns the config setting causing the problem.
+         * @return the path of the problem setting
+         */
         public String path() {
             return path;
         }
@@ -330,12 +333,16 @@ public abstract class ConfigException extends RuntimeException implements Serial
         /**
          * Returns where the problem occurred (origin may include info on the
          * file, line number, etc.).
+         * @return the origin of the problem setting
          */
         public ConfigOrigin origin() {
             return origin;
         }
 
-        /** Returns a description of the problem. */
+        /**
+         * Returns a description of the problem.
+         * @return description of the problem
+         */
         public String problem() {
             return problem;
         }

config/src/main/java/com/typesafe/config/ConfigFactory.java

@@ -86,8 +86,8 @@ public final class ConfigFactory {
      * {@link #defaultReference(ClassLoader)} and to load only the overrides use
      * {@link #defaultOverrides(ClassLoader)}.
      * 
-     * @param loader
-     * @param resourceBasename
+     * @param loader class loader to look for resources in
+     * @param resourceBasename basename (no .conf/.json/.properties suffix)
      * @return configuration for an application relative to given class loader
      */
     public static Config load(ClassLoader loader, String resourceBasename) {
@@ -396,7 +396,7 @@ public final class ConfigFactory {
      * Like {@link #defaultReference()} but allows you to specify a class loader
      * to use rather than the current context class loader.
      *
-     * @param loader
+     * @param loader class loader to look for resources in
      * @return the default reference config for this class loader
      */
     public static Config defaultReference(ClassLoader loader) {
@@ -426,7 +426,7 @@ public final class ConfigFactory {
      * Like {@link #defaultOverrides()} but allows you to specify a class loader
      * to use rather than the current context class loader.
      *
-     * @param loader
+     * @param loader class loader to look for resources in
      * @return the default override configuration
      */
     public static Config defaultOverrides(ClassLoader loader) {
@@ -490,7 +490,7 @@ public final class ConfigFactory {
      *
      * @since 1.3.0
      *
-     * @param loader
+     * @param loader class loader to look for resources in
      * @return the default application configuration
      */
     public static Config defaultApplication(ClassLoader loader) {
@@ -502,7 +502,7 @@ public final class ConfigFactory {
      *
      * @since 1.3.0
      *
-     * @param parseOptions the options
+     * @param options the options
      * @return the default application configuration
      */
     public static Config defaultApplication(ConfigParseOptions options) {
@@ -620,6 +620,7 @@ public final class ConfigFactory {
      * @param properties
      *            a Java Properties object
      * @param options
+     *            the parse options
      * @return the parsed configuration
      */
     public static Config parseProperties(Properties properties,
@@ -877,6 +878,9 @@ public final class ConfigFactory {
      * Like {@link #parseResources(ClassLoader,String,ConfigParseOptions)} but
      * uses thread's current context class loader if none is set in the
      * ConfigParseOptions.
+     * @param resource the resource name
+     * @param options parse options
+     * @return the parsed configuration
      */
     public static Config parseResources(String resource, ConfigParseOptions options) {
         ConfigParseOptions withLoader = ensureClassLoader(options, "parseResources");
@@ -886,6 +890,8 @@ public final class ConfigFactory {
     /**
      * Like {@link #parseResources(ClassLoader,String)} but uses thread's
      * current context class loader.
+     * @param resource the resource name
+     * @return the parsed configuration
      */
     public static Config parseResources(String resource) {
         return parseResources(resource, ConfigParseOptions.defaults());
@@ -895,6 +901,9 @@ public final class ConfigFactory {
      * Like
      * {@link #parseResourcesAnySyntax(ClassLoader,String,ConfigParseOptions)}
      * but uses thread's current context class loader.
+     * @param resourceBasename the resource basename (no file type suffix)
+     * @param options parse options
+     * @return the parsed configuration
      */
     public static Config parseResourcesAnySyntax(String resourceBasename, ConfigParseOptions options) {
         return ConfigImpl.parseResourcesAnySyntax(resourceBasename, options).toConfig();
@@ -903,15 +912,31 @@ public final class ConfigFactory {
     /**
      * Like {@link #parseResourcesAnySyntax(ClassLoader,String)} but uses
      * thread's current context class loader.
+     * @param resourceBasename the resource basename (no file type suffix)
+     * @return the parsed configuration
      */
     public static Config parseResourcesAnySyntax(String resourceBasename) {
         return parseResourcesAnySyntax(resourceBasename, ConfigParseOptions.defaults());
     }
 
+    /**
+     * Parses a string (which should be valid HOCON or JSON by default, or
+     * the syntax specified in the options otherwise).
+     *
+     * @param s string to parse
+     * @param options parse options
+     * @return the parsed configuration
+     */
     public static Config parseString(String s, ConfigParseOptions options) {
         return Parseable.newString(s, options).parse().toConfig();
     }
 
+    /**
+     * Parses a string (which should be valid HOCON or JSON).
+     *
+     * @param s string to parse
+     * @return the parsed configuration
+     */
     public static Config parseString(String s) {
         return parseString(s, ConfigParseOptions.defaults());
     }
@@ -932,7 +957,7 @@ public final class ConfigFactory {
      * object of "b". The caller of this method should ensure that doesn't
      * happen.
      *
-     * @param values
+     * @param values map from paths to plain Java objects
      * @param originDescription
      *            description of what this map represents, like a filename, or
      *            "default settings" (origin description is used in error
@@ -948,7 +973,7 @@ public final class ConfigFactory {
      * See the other overload of {@link #parseMap(Map, String)} for details,
      * this one just uses a default origin description.
      *
-     * @param values
+     * @param values map from paths to plain Java values
      * @return the map converted to a {@code Config}
      */
     public static Config parseMap(Map<String, ? extends Object> values) {

config/src/main/java/com/typesafe/config/ConfigIncluder.java

@@ -23,7 +23,7 @@ public interface ConfigIncluder {
      * the fallback is the same one you already have. The same fallback may be
      * added repeatedly.
      *
-     * @param fallback
+     * @param fallback the previous includer for chaining
      * @return a new includer
      */
     ConfigIncluder withFallback(ConfigIncluder fallback);

config/src/main/java/com/typesafe/config/ConfigMemorySize.java

@@ -23,6 +23,8 @@ public final class ConfigMemorySize {
      * Constructs a ConfigMemorySize representing the given
      * number of bytes.
      * @since 1.3.0
+     * @param bytes a number of bytes
+     * @return an instance representing the number of bytes
      */
     public static ConfigMemorySize ofBytes(long bytes) {
         return new ConfigMemorySize(bytes);
@@ -31,6 +33,7 @@ public final class ConfigMemorySize {
     /**
      * Gets the size in bytes.
      * @since 1.3.0
+     * @return how many bytes
      */
     public long toBytes() {
         return bytes;

config/src/main/java/com/typesafe/config/ConfigOrigin.java

@@ -79,17 +79,17 @@ public interface ConfigOrigin {
      *         none
      */
     public List<String> comments();
-    
+
     /**
      * Returns a {@code ConfigOrigin} based on this one, but with the given
      * comments. Does not modify this instance or any {@code ConfigValue}s with
-     * this origin (since they are immutable).  To set the returned origin to a 
+     * this origin (since they are immutable).  To set the returned origin to a
      * {@code ConfigValue}, use {@link ConfigValue#withOrigin}.
-     * 
+     *
      * <p>
      * Note that when the given comments are equal to the comments on this object,
      * a new instance may not be created and {@code this} is returned directly.
-     * 
+     *
      * @param comments the comments used on the returned origin
      * @return the ConfigOrigin with the given comments
      */
@@ -97,17 +97,17 @@ public interface ConfigOrigin {
 
     /**
      * Returns a {@code ConfigOrigin} based on this one, but with the given
-     * line number. This origin must be a FILE, URL or RESOURCE. Does not modify 
+     * line number. This origin must be a FILE, URL or RESOURCE. Does not modify
      * this instance or any {@code ConfigValue}s with this origin (since they are
      * immutable).  To set the returned origin to a  {@code ConfigValue}, use
-     * {@link ConfigValue#withOrigin}. 
-     * 
+     * {@link ConfigValue#withOrigin}.
+     *
      * <p>
      * Note that when the given lineNumber are equal to the lineNumber on this
      * object, a new instance may not be created and {@code this} is returned
      * directly.
-     * 
-     * @param comments the comments used on the returned origin
+     *
+     * @param lineNumber the new line number
      * @return the created ConfigOrigin
      */
     public ConfigOrigin withLineNumber(int lineNumber);

config/src/main/java/com/typesafe/config/ConfigOriginFactory.java

@@ -15,43 +15,43 @@ import com.typesafe.config.impl.ConfigImpl;
 public final class ConfigOriginFactory {
     private ConfigOriginFactory() {
     }
-    
+
     /**
      * Returns the default origin for values when no other information is
      * provided. This is the origin used in {@link ConfigValueFactory
      * #fromAnyRef(Object)}.
-     * 
+     *
      * @return the default origin
      */
     public static ConfigOrigin newSimple() {
         return newSimple(null);
     }
-    
+
     /**
-     * Returns a origin with the given description.
-     * 
+     * Returns an origin with the given description.
+     *
      * @param description brief description of what the origin is
-     * @return
+     * @return a new origin
      */
     public static ConfigOrigin newSimple(String description) {
         return ConfigImpl.newSimpleOrigin(description);
     }
-    
+
     /**
      * Creates a file origin with the given filename.
-     * 
+     *
      * @param filename the filename of this origin
-     * @return
+     * @return a new origin
      */
     public static ConfigOrigin newFile(String filename) {
         return ConfigImpl.newFileOrigin(filename);
     }
-    
+
     /**
      * Creates a url origin with the given URL object.
-     * 
+     *
      * @param url the url of this origin
-     * @return
+     * @return a new origin
      */
     public static ConfigOrigin newURL(URL url) {
         return ConfigImpl.newURLOrigin(url);

config/src/main/java/com/typesafe/config/ConfigParseOptions.java

@@ -67,7 +67,7 @@ public final class ConfigParseOptions {
      * library to come up with something automatically. This description is the
      * basis for the {@link ConfigOrigin} of the parsed values.
      *
-     * @param originDescription
+     * @param originDescription description to put in the {@link ConfigOrigin}
      * @return options with the origin description set
      */
     public ConfigParseOptions setOriginDescription(String originDescription) {
@@ -99,7 +99,7 @@ public final class ConfigParseOptions {
      * a file) is missing. Set to true to just return an empty document in that
      * case.
      *
-     * @param allowMissing
+     * @param allowMissing true to silently ignore missing item
      * @return options with the "allow missing" flag set
      */
     public ConfigParseOptions setAllowMissing(boolean allowMissing) {
@@ -117,7 +117,7 @@ public final class ConfigParseOptions {
     /**
      * Set a ConfigIncluder which customizes how includes are handled.
      *
-     * @param includer
+     * @param includer the includer to use or null for default
      * @return new version of the parse options with different includer
      */
     public ConfigParseOptions setIncluder(ConfigIncluder includer) {

config/src/main/java/com/typesafe/config/ConfigParseable.java

@@ -24,12 +24,14 @@ public interface ConfigParseable {
      * @param options
      *            parse options, should be based on the ones from
      *            {@link ConfigParseable#options options()}
+     * @return the parsed object
      */
     ConfigObject parse(ConfigParseOptions options);
 
     /**
      * Returns a {@link ConfigOrigin} describing the origin of the parseable
      * item.
+     * @return the origin of the parseable item
      */
     ConfigOrigin origin();
 
@@ -37,6 +39,7 @@ public interface ConfigParseable {
      * Get the initial options, which can be modified then passed to parse().
      * These options will have the right description, includer, and other
      * parameters already set up.
+     * @return the initial options
      */
     ConfigParseOptions options();
 }

config/src/main/java/com/typesafe/config/ConfigValue.java

@@ -40,6 +40,7 @@ public interface ConfigValue extends ConfigMergeable {
      * {@code List<Object>}, or {@code null}, matching the {@link #valueType()}
      * of this {@code ConfigValue}. If the value is a {@link ConfigObject} or
      * {@link ConfigList}, it is recursively unwrapped.
+     * @return a plain Java value corresponding to this ConfigValue
      */
     Object unwrapped();
 

config/src/main/java/com/typesafe/config/ConfigValueFactory.java

@@ -91,8 +91,8 @@ public final class ConfigValueFactory {
      * See also {@link ConfigFactory#parseMap(Map,String)} which interprets the
      * keys in the map as path expressions.
      * 
-     * @param values
-     * @param originDescription
+     * @param values map from keys to plain Java values
+     * @param originDescription description to use in {@link ConfigOrigin} of created values
      * @return a new {@link ConfigObject} value
      */
     public static ConfigObject fromMap(Map<String, ? extends Object> values,
@@ -104,9 +104,9 @@ public final class ConfigValueFactory {
      * See the {@link #fromAnyRef(Object,String)} documentation for details.
      * This is a typesafe wrapper that only works on {@link java.lang.Iterable}
      * and returns {@link ConfigList} rather than {@link ConfigValue}.
-     * 
-     * @param values
-     * @param originDescription
+     *
+     * @param values list of plain Java values
+     * @param originDescription description to use in {@link ConfigOrigin} of created values
      * @return a new {@link ConfigList} value
      */
     public static ConfigList fromIterable(Iterable<? extends Object> values,
@@ -118,7 +118,7 @@ public final class ConfigValueFactory {
      * See the other overload {@link #fromAnyRef(Object,String)} for details,
      * this one just uses a default origin description.
      *
-     * @param object
+     * @param object a plain Java value
      * @return a new {@link ConfigValue}
      */
     public static ConfigValue fromAnyRef(Object object) {
@@ -133,7 +133,7 @@ public final class ConfigValueFactory {
      * See also {@link ConfigFactory#parseMap(Map)} which interprets the keys in
      * the map as path expressions.
      *
-     * @param values
+     * @param values map from keys to plain Java values
      * @return a new {@link ConfigObject}
      */
     public static ConfigObject fromMap(Map<String, ? extends Object> values) {
@@ -144,7 +144,7 @@ public final class ConfigValueFactory {
      * See the other overload of {@link #fromIterable(Iterable, String)} for
      * details, this one just uses a default origin description.
      *
-     * @param values
+     * @param values list of plain Java values
      * @return a new {@link ConfigList}
      */
     public static ConfigList fromIterable(Iterable<? extends Object> values) {

config/src/main/java/com/typesafe/config/impl/ConfigBeanImpl.java

@@ -23,11 +23,19 @@ import com.typesafe.config.ConfigMemorySize;
 import com.typesafe.config.ConfigValue;
 import com.typesafe.config.ConfigValueType;
 
+/**
+ * Internal implementation detail, not ABI stable, do not touch.
+ * For use only by the {@link com.typesafe.config} package.
+ */
 public class ConfigBeanImpl {
 
     /**
      * This is public ONLY for use by the "config" package, DO NOT USE this ABI
      * may change.
+     * @param <T> type of the bean
+     * @param config config to use
+     * @param clazz class of the bean
+     * @return the bean instance
      */
     public static <T> T createInternal(Config config, Class<T> clazz) {
         if (((SimpleConfig)config).root().resolveStatus() != ResolveStatus.RESOLVED)

config/src/main/java/com/typesafe/config/impl/ConfigImpl.java

@@ -27,7 +27,10 @@ import com.typesafe.config.ConfigParseable;
 import com.typesafe.config.ConfigValue;
 import com.typesafe.config.impl.SimpleIncluder.NameSource;
 
-/** This is public but is only supposed to be used by the "config" package */
+/**
+ * Internal implementation detail, not ABI stable, do not touch.
+ * For use only by the {@link com.typesafe.config} package.
+ */
 public class ConfigImpl {
 
     private static class LoaderCache {
@@ -78,7 +81,6 @@ public class ConfigImpl {
         static final LoaderCache cache = new LoaderCache();
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static Config computeCachedConfig(ClassLoader loader, String key,
             Callable<Config> updater) {
         LoaderCache cache;
@@ -118,21 +120,18 @@ public class ConfigImpl {
         }
     };
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigObject parseResourcesAnySyntax(Class<?> klass, String resourceBasename,
             ConfigParseOptions baseOptions) {
         NameSource source = new ClasspathNameSourceWithClass(klass);
         return SimpleIncluder.fromBasename(source, resourceBasename, baseOptions);
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigObject parseResourcesAnySyntax(String resourceBasename,
             ConfigParseOptions baseOptions) {
         NameSource source = new ClasspathNameSource();
         return SimpleIncluder.fromBasename(source, resourceBasename, baseOptions);
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigObject parseFileAnySyntax(File basename, ConfigParseOptions baseOptions) {
         NameSource source = new FileNameSource();
         return SimpleIncluder.fromBasename(source, basename.getPath(), baseOptions);
@@ -144,7 +143,6 @@ public class ConfigImpl {
         return emptyObject(origin);
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static Config emptyConfig(String originDescription) {
         return emptyObject(originDescription).toConfig();
     }
@@ -191,13 +189,11 @@ public class ConfigImpl {
             return SimpleConfigOrigin.newSimple(originDescription);
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigValue fromAnyRef(Object object, String originDescription) {
         ConfigOrigin origin = valueOrigin(originDescription);
         return fromAnyRef(object, origin, FromMapMode.KEYS_ARE_KEYS);
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigObject fromPathMap(
             Map<String, ? extends Object> pathMap, String originDescription) {
         ConfigOrigin origin = valueOrigin(originDescription);
@@ -328,12 +324,10 @@ public class ConfigImpl {
         }
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static Config systemPropertiesAsConfig() {
         return systemPropertiesAsConfigObject().toConfig();
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static void reloadSystemPropertiesConfig() {
         // ConfigFactory.invalidateCaches() relies on this having the side
         // effect that it drops all caches
@@ -365,12 +359,10 @@ public class ConfigImpl {
         }
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static Config envVariablesAsConfig() {
         return envVariablesAsConfigObject().toConfig();
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static Config defaultReference(final ClassLoader loader) {
         return computeCachedConfig(loader, "defaultReference", new Callable<Config>() {
             @Override
@@ -427,7 +419,6 @@ public class ConfigImpl {
         }
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static boolean traceLoadsEnabled() {
         try {
             return DebugHolder.traceLoadsEnabled();
@@ -470,8 +461,7 @@ public class ConfigImpl {
         else
             return new ConfigException.NotResolved(newMessage, original);
     }
-    
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
+
     public static ConfigOrigin newSimpleOrigin(String description) {
         if (description == null) {
             return defaultValueOrigin;
@@ -480,14 +470,11 @@ public class ConfigImpl {
         }
     }
 
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
     public static ConfigOrigin newFileOrigin(String filename) {
         return SimpleConfigOrigin.newFile(filename);
     }
-    
-    /** For use ONLY by library internals, DO NOT TOUCH not guaranteed ABI */
+
     public static ConfigOrigin newURLOrigin(URL url) {
         return SimpleConfigOrigin.newURL(url);
     }
-    
 }

config/src/main/java/com/typesafe/config/impl/ConfigImplUtil.java

@@ -16,8 +16,10 @@ import java.util.List;
 import com.typesafe.config.ConfigException;
 import com.typesafe.config.ConfigOrigin;
 
-
-/** This is public just for the "config" package to use, don't touch it */
+/**
+ * Internal implementation detail, not ABI stable, do not touch.
+ * For use only by the {@link com.typesafe.config} package.
+ */
 final public class ConfigImplUtil {
     static boolean equalsHandlingNull(Object a, Object b) {
         if (a == null && b != null)
@@ -30,10 +32,6 @@ final public class ConfigImplUtil {
             return a.equals(b);
     }
 
-    /**
-     * This is public ONLY for use by the "config" package, DO NOT USE this ABI
-     * may change.
-     */
     public static String renderJsonString(String s) {
         StringBuilder sb = new StringBuilder();
         sb.append('"');
@@ -117,7 +115,6 @@ final public class ConfigImplUtil {
         }
     }
 
-    /** This is public just for the "config" package to use, don't touch it! */
     public static String unicodeTrim(String s) {
         // this is dumb because it looks like there aren't any whitespace
         // characters that need surrogate encoding. But, points for
@@ -166,7 +163,7 @@ final public class ConfigImplUtil {
         return s.substring(start, end);
     }
 
-    /** This is public just for the "config" package to use, don't touch it! */
+
     public static ConfigException extractInitializerError(ExceptionInInitializerError e) {
         Throwable cause = e.getCause();
         if (cause != null && cause instanceof ConfigException) {
@@ -192,26 +189,14 @@ final public class ConfigImplUtil {
         }
     }
 
-    /**
-     * This is public ONLY for use by the "config" package, DO NOT USE this ABI
-     * may change. You can use the version in ConfigUtil instead.
-     */
     public static String joinPath(String... elements) {
         return (new Path(elements)).render();
     }
 
-    /**
-     * This is public ONLY for use by the "config" package, DO NOT USE this ABI
-     * may change. You can use the version in ConfigUtil instead.
-     */
     public static String joinPath(List<String> elements) {
         return joinPath(elements.toArray(new String[0]));
     }
 
-    /**
-     * This is public ONLY for use by the "config" package, DO NOT USE this ABI
-     * may change. You can use the version in ConfigUtil instead.
-     */
     public static List<String> splitPath(String path) {
         Path p = Path.newPath(path);
         List<String> elements = new ArrayList<String>();

config/src/main/java/com/typesafe/config/impl/Parseable.java

@@ -35,18 +35,22 @@ import com.typesafe.config.ConfigSyntax;
 import com.typesafe.config.ConfigValue;
 
 /**
- * This is public but it's only for use by the config package; DO NOT TOUCH. The
- * point of this class is to avoid "propagating" each overload on
- * "thing which can be parsed" through multiple interfaces. Most interfaces can
- * have just one overload that takes a Parseable. Also it's used as an abstract
- * "resource handle" in the ConfigIncluder interface.
+ * Internal implementation detail, not ABI stable, do not touch.
+ * For use only by the {@link com.typesafe.config} package.
+ * The point of this class is to avoid "propagating" each
+ * overload on "thing which can be parsed" through multiple
+ * interfaces. Most interfaces can have just one overload that
+ * takes a Parseable. Also it's used as an abstract "resource
+ * handle" in the ConfigIncluder interface.
  */
 public abstract class Parseable implements ConfigParseable {
     private ConfigIncludeContext includeContext;
     private ConfigParseOptions initialOptions;
     private ConfigOrigin initialOrigin;
 
-
+    /**
+     * Internal implementation detail, not ABI stable, do not touch.
+     */
     protected interface Relativizer {
         ConfigParseable relativeTo(String filename);
     }
@@ -383,10 +387,8 @@ public abstract class Parseable implements ConfigParseable {
         }
     }
 
-    /**
-     * note that we will never close this reader; you have to do it when parsing
-     * is complete.
-     */
+    // note that we will never close this reader; you have to do it when parsing
+    // is complete.
     public static Parseable newReader(Reader reader, ConfigParseOptions options) {
 
         return new ParseableReader(doNotClose(reader), options);

config/src/main/java/com/typesafe/config/impl/package.html

@@ -0,0 +1,25 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<!--
+ Copyright (C) 2011 Typesafe Inc. <http://typesafe.com>
+-->
+
+</head>
+<body bgcolor="white">
+
+<p>
+Internal implementation details that can change ABI at any time.
+</p>
+
+<p>
+Please check out the {@link com.typesafe.config.Config public API} instead, unless
+you're interested in browsing implementation details. None of the ABI
+under <code>impl</code> has any guarantees; it will change whenever someone
+feels like changing it. If you feel you need access to something
+in <code>impl</code>, <a href="https://github.com/typesafehub/config/issues">please
+file a feature request</a>.
+</p>
+
+</body>
+</html>