Updating doc blocks in Debugger and CakeLog.

lib/Cake/Log/CakeLog.php

@@ -42,6 +42,19 @@
  * using CakeLogs's methods.  If you don't configure any adapters, and write to the logs
  * a default FileLog will be autoconfigured for you.
  *
+ * ### Configuring Log adapters
+ *
+ * You can configure log adapters in your applications `bootstrap.php` file.  A sample configuration
+ * would look like:
+ *
+ * `CakeLog::config('my_log', array('engine' => 'FileLog'));`
+ *
+ * See the documentation on CakeLog::config() for more detail.
+ *
+ * ### Writing to the log
+ *
+ * You write to the logs using CakeLog::write().  See its documentation for more information.
+ *
  * @package       Cake.Log
  */
 class CakeLog {
@@ -69,11 +82,7 @@ class CakeLog {
  *
  * Will configure a FileLog instance to use the specified path.  All options that are not `engine`
  * are passed onto the logging adapter, and handled there.  Any class can be configured as a logging
- * adapter as long as it implements a `write` method with the following signature.
- *
- * `write($type, $message)`
- *
- * For an explaination of these parameters, see CakeLog::write()
+ * adapter as long as it implements the methods in CakeLogInterface.
  *
  * @param string $key The keyname for this logger, used to remove the logger later.
  * @param array $config Array of configuration information for the logger

lib/Cake/Utility/Debugger.php

@@ -191,14 +191,15 @@ public static function &getInstance($class = null) {
 	}
 
 /**
- * Formats and outputs the contents of the supplied variable.
+ * Recursively formats and outputs the contents of the supplied variable.
+ *
  *
  * @param $var mixed the variable to dump
  * @return void
  * @see Debugger::exportVar()
  * @static
  * @link http://book.cakephp.org/view/1191/Using-the-Debugger-Class
-*/
+ */
 	public static function dump($var) {
 		pr(self::exportVar($var));
 	}
@@ -405,12 +406,22 @@ public static function trimPath($path) {
 	}
 
 /**
- * Grabs an excerpt from a file and highlights a given line of code
+ * Grabs an excerpt from a file and highlights a given line of code.
+ *
+ * Usage:
+ *
+ * `Debugger::excerpt('/path/to/file', 100, 4);`
+ *
+ * The above would return an array of 8 items. The 4th item would be the provided line,
+ * and would be wrapped in `<span class="code-highlight"></span>`.  All of the lines
+ * are processed with highlight_string() as well, so they have basic PHP syntax highlighting
+ * applied.
  *
  * @param string $file Absolute path to a PHP file
  * @param integer $line Line number to highlight
  * @param integer $context Number of lines of context to extract above and below $line
  * @return array Set of lines highlighted
+ * @see http://php.net/highlight_string
  * @static
  * @link http://book.cakephp.org/view/1191/Using-the-Debugger-Class
  */
@@ -441,6 +452,20 @@ public static function excerpt($file, $line, $context = 2) {
 /**
  * Converts a variable to a string for debug output.
  *
+ * *Note:* The following keys will have their contents replaced with 
+ * `*****`:
+ *
+ *  - password
+ *  - login
+ *  - host
+ *  - database
+ *  - port
+ *  - prefix
+ *  - schema
+ *
+ * This is done to protect database credentials, which could be accidentally
+ * shown in an error message if CakePHP is deployed in development mode.
+ *
  * @param string $var Variable to convert
  * @return string Variable as a formatted string
  * @static