diff --git a/lib/Cake/Configure/IniReader.php b/lib/Cake/Configure/IniReader.php
index 26d6be7fb..cba69cd29 100644
--- a/lib/Cake/Configure/IniReader.php
+++ b/lib/Cake/Configure/IniReader.php
@@ -23,14 +23,29 @@
  * regards to boolean and null values.
  *
  * In addition to the native parse_ini_file features, IniReader also allows you
- * to create nested array structures through usage of . delimited names.  This allows
+ * to create nested array structures through usage of `.` delimited names.  This allows
  * you to create nested arrays structures in an ini config file. For example:
  *
  * `db.password = secret` would turn into `array('db' => array('password' => 'secret'))`
  *
- * You can nest properties as deeply as needed using .'s.  IniReader also manipulates
- * how the special ini values of 'yes', 'no', 'on', 'off', 'null' are handled.
- * These values will be converted to their boolean equivalents.
+ * You can nest properties as deeply as needed using `.`'s. In addition to using `.` you
+ * can use standard ini section notation to create nested structures:
+ *
+ * {{{
+ * [section]
+ * key = value
+ * }}}
+ *
+ * Once loaded into Configure, the above would be accessed using:
+ *
+ * `Configure::read('section.key');
+ *
+ * You can combine `.` separated values with sections to create more deeply
+ * nested structures.
+ *
+ * IniReader also manipulates how the special ini values of 
+ * 'yes', 'no', 'on', 'off', 'null' are handled. These values will be 
+ * converted to their boolean equivalents.
  *
  * @package cake.config
  * @see http://php.net/parse_ini_file
@@ -56,7 +71,8 @@ class IniReader implements ConfigReaderInterface {
  * ini files that are on the filesystem.
  *
  * @param string $path Path to load ini config files from.
- * @param string $section Only get one section.
+ * @param string $section Only get one section, leave null to parse and fetch
+ *     all sections in the ini file.
  */
 	public function __construct($path, $section = null) {
 		$this->_path = $path;
@@ -66,7 +82,8 @@ class IniReader implements ConfigReaderInterface {
 /**
  * Read an ini file and return the results as an array.
  *
- * @param string $file Name of the file to read.
+ * @param string $file Name of the file to read. The chosen file
+ *    must be on the reader's path.
  * @return array
  */
 	public function read($file) {
@@ -116,4 +133,4 @@ class IniReader implements ConfigReaderInterface {
 		}
 		return $values;
 	}
-}
\ No newline at end of file
+}
diff --git a/lib/Cake/Configure/PhpReader.php b/lib/Cake/Configure/PhpReader.php
index cb2ea043a..efed990c6 100644
--- a/lib/Cake/Configure/PhpReader.php
+++ b/lib/Cake/Configure/PhpReader.php
@@ -21,6 +21,9 @@
  * PHP Reader allows Configure to load configuration values from
  * files containing simple PHP arrays.
  *
+ * Files compatible with PhpReader should define a `$config` variable, that
+ * contains all of the configuration data contained in the file.
+ *
  * @package cake.libs.config
  */
 class PhpReader implements ConfigReaderInterface {
@@ -46,12 +49,11 @@ class PhpReader implements ConfigReaderInterface {
 /**
  * Read a config file and return its contents.
  *
- * Keys with `.` will be treated as values in plugins.  Instead of reading from
+ * Files with `.` in the name will be treated as values in plugins.  Instead of reading from
  * the initialized path, plugin keys will be located using App::pluginPath().
  *
- *
  * @param string $key The identifier to read from.  If the key has a . it will be treated
- *   as a plugin prefix.
+ *  as a plugin prefix.
  * @return array Parsed configuration values.
  * @throws ConfigureException when files don't exist or they don't contain `$config`.
  *  Or when files contain '..' as this could lead to abusive reads.