add some more API docs

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

@@ -4,11 +4,33 @@ import java.util.concurrent.TimeUnit;
 
 import com.typesafe.config.impl.ConfigImpl;
 
+/**
+ * This class holds some global static methods for the config package.
+ */
 public final class Config {
+    /**
+     * Loads a configuration object.
+     *
+     * @param configConfig
+     *            configuration for the configuration.
+     * @return a configuration object
+     */
     public static ConfigObject load(ConfigConfig configConfig) {
         return ConfigImpl.loadConfig(configConfig);
     }
 
+    /**
+     * Loads a configuration for the given root path. The root path should be a
+     * short word that scopes the package being configured; typically it's the
+     * package name or something similar. System properties overriding values in
+     * the configuration will have to be prefixed with the root path. The root
+     * path may have periods in it if you like but other punctuation or
+     * whitespace will probably cause you headaches. Example root paths: "akka",
+     * "sbt", "jsoup", "heroku", "mongo", etc.
+     * @param rootPath
+     *            the configuration "domain"
+     * @return configuration object for the requested root path
+     */
     public static ConfigObject load(String rootPath) {
         return ConfigImpl.loadConfig(new ConfigConfig(rootPath));
     }

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

@@ -7,10 +7,22 @@ public final class ConfigConfig {
 
     private String rootPath;
 
+    /**
+     * Creates a new configuration configuration.
+     *
+     * @param rootPath
+     *            the root path as described in Config.load() docs
+     */
     public ConfigConfig(String rootPath) {
         this.rootPath = rootPath;
     }
 
+    /**
+     * Get the configured root path. This method would be used by code
+     * implementing a configuration backend; don't worry about it.
+     *
+     * @return the root path
+     */
     public String rootPath() {
         return rootPath;
     }

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

@@ -1,5 +1,8 @@
 package com.typesafe.config;
 
+/**
+ * All exceptions thrown by the library are subclasses of ConfigException.
+ */
 public class ConfigException extends RuntimeException {
     private static final long serialVersionUID = 1L;
 
@@ -20,6 +23,11 @@ public class ConfigException extends RuntimeException {
         this(message, null);
     }
 
+    /**
+     * Exception indicating that the type of a value does not match the type you
+     * requested.
+     *
+     */
     public static class WrongType extends ConfigException {
         private static final long serialVersionUID = 1L;
 
@@ -89,6 +97,12 @@ public class ConfigException extends RuntimeException {
         }
     }
 
+    /**
+     * Exception indicating that a value was messed up, for example you may have
+     * asked for a duration and the value can't be sensibly parsed as a
+     * duration.
+     *
+     */
     public static class BadValue extends ConfigException {
         private static final long serialVersionUID = 1L;
 
@@ -149,6 +163,10 @@ public class ConfigException extends RuntimeException {
         }
     }
 
+    /**
+     * Exception indicating that there was an IO error.
+     *
+     */
     public static class IO extends ConfigException {
         private static final long serialVersionUID = 1L;
 
@@ -161,6 +179,10 @@ public class ConfigException extends RuntimeException {
         }
     }
 
+    /**
+     * Exception indicating that there was a parse error.
+     *
+     */
     public static class Parse extends ConfigException {
         private static final long serialVersionUID = 1L;
 

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

@@ -4,16 +4,26 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * A Config is a read-only configuration object, which may have nested child
+ * A ConfigObject is a read-only configuration object, which may have nested
- * objects. Implementations of Config should be immutable (at least from the
+ * child objects. Implementations of ConfigObject should be immutable (at least
- * perspective of anyone using this interface).
+ * from the perspective of anyone using this interface).
  *
  * The getters all have the same semantics; they throw ConfigException.Missing
  * if the value is entirely unset, and ConfigException.WrongType if you ask for
  * a type that the value can't be converted to. ConfigException.Null is a
- * subclass of ConfigException.WrongType thrown if the value is null.
+ * subclass of ConfigException.WrongType thrown if the value is null. The "path"
- *
+ * parameters for all the getters have periods between the key names, so the
- * TODO add OrNull variants of all these getters?
+ * path "a.b.c" looks for key c in object b in object a in the root object.
+ * 
+ * 
+ * TODO If you need to look up a key with a period in its name, there isn't a
+ * way to do it right now.
+ * 
+ * TODO add OrNull variants of all these getters? Or better to avoid convenience
+ * API for that?
+ * 
+ * TODO should it implement Map<String, ? extends ConfigValue> with the mutators
+ * throwing ?
  */
 public interface ConfigObject extends ConfigValue {
 
@@ -31,8 +41,22 @@ public interface ConfigObject extends ConfigValue {
 
     ConfigObject getObject(String path);
 
+    /**
+     * Gets the value at the path as an unwrapped Java boxed value (Boolean,
+     * Integer, Long, etc.)
+     */
     Object getAny(String path);
 
+    /**
+     * Gets the value at the path as a ConfigValue.
+     *
+     * TODO conceptually if we want to match a read-only subset of the
+     * Map<String, ? extends ConfigValue> interface, we would need to take a key
+     * instead of a path here and return null instead of throwing an exception.
+     *
+     * @param path
+     * @return
+     */
     ConfigValue get(String path);
 
     /** Get value as a size in bytes (parses special strings like "128M") */

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

@@ -1,5 +1,9 @@
 package com.typesafe.config;
 
+/**
+ * ConfigOrigin is used to track the origin (such as filename and line number)
+ * of a ConfigValue or other object. The origin is used in error messages.
+ */
 public interface ConfigOrigin {
     public String description();
 }

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

@@ -2,15 +2,26 @@ package com.typesafe.config;
 
 /**
  * Interface implemented by any configuration value. From the perspective of
- * users of this interface, the object should be immutable.
+ * users of this interface, the object is immutable. It is therefore safe to use
+ * from multiple threads.
  */
 public interface ConfigValue {
+    /**
+     * The origin of the value, for debugging and error messages.
+     * 
+     * @return where the value came from
+     */
     ConfigOrigin origin();
 
+    /**
+     * The type of the value; matches the JSON type schema.
+     * 
+     * @return value's type
+     */
     ConfigValueType valueType();
 
     /**
-     * Returns the config value as a plain Java value, should be a String,
+     * Returns the config value as a plain Java boxed value, should be a String,
      * Number, etc. matching the valueType() of the ConfigValue.
      */
     Object unwrapped();

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

@@ -1,5 +1,8 @@
 package com.typesafe.config;
 
+/**
+ * The type of a configuration value. Value types follow the JSON type schema.
+ */
 public enum ConfigValueType {
     OBJECT, LIST, NUMBER, BOOLEAN, NULL, STRING
 }