From 79bdcc1446d300562b120343e0b7a5d8baf863d6 Mon Sep 17 00:00:00 2001
From: nacin <nacin@1a063a9b-81f0-0310-95a4-ce76da25c4cd>
Date: Wed, 17 Feb 2010 13:14:45 +0000
Subject: [PATCH] Better inline documentation for WP_DEBUG, WP_DEBUG_DISPLAY,
 and WP_DEBUG_LOG. Fixes #11987

git-svn-id: http://svn.automattic.com/wordpress/trunk@13176 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/default-constants.php |  8 +++++---
 wp-includes/load.php              | 26 +++++++++++++++++++-------
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/wp-includes/default-constants.php b/wp-includes/default-constants.php
index d6dc5a1e1..2a07c1d4f 100644
--- a/wp-includes/default-constants.php
+++ b/wp-includes/default-constants.php
@@ -7,7 +7,9 @@
 
 /**
  * Defines initial WordPress constants
- * 
+ *
+ * @see wp_debug_mode()
+ *
  * @since 3.0.0
  */
 function wp_initial_constants( ) {
@@ -43,11 +45,11 @@ function wp_initial_constants( ) {
 	if ( !defined('WP_DEBUG') )
 		define( 'WP_DEBUG', false );
 
-	// Add define('WP_DEBUG_DISPLAY', false); to wp-config.php to use the globally configured setting for display_errors and not force it to On
+	// Add define('WP_DEBUG_DISPLAY', false); to wp-config.php use the globally configured setting for display_errors and not force errors to be displayed.
 	if ( !defined('WP_DEBUG_DISPLAY') )
 		define( 'WP_DEBUG_DISPLAY', true );
 
-	// Add define('WP_DEBUG_LOG', true); to enable php debug logging to WP_CONTENT_DIR/debug.log
+	// Add define('WP_DEBUG_LOG', true); to enable error logging to wp-content/debug.log.
 	if ( !defined('WP_DEBUG_LOG') )
 		define('WP_DEBUG_LOG', false);
 
diff --git a/wp-includes/load.php b/wp-includes/load.php
index 0640fde78..0993a1468 100644
--- a/wp-includes/load.php
+++ b/wp-includes/load.php
@@ -208,16 +208,28 @@ function timer_stop( $display = 0, $precision = 3 ) { // if called like timer_st
 }
 
 /**
- * Sets PHP error handling.
+ * Sets PHP error handling and handles WordPress debug mode.
  *
- * Add <code>define('WP_DEBUG', true);</code> to wp-config.php to enable
- * the reporting of notices during development.
+ * Uses three constants: WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG. All three can be
+ * defined in wp-config.php. Example: <code> define( 'WP_DEBUG', true ); </code>
  *
- * Add <code>define('WP_DEBUG_DISPLAY', false);</code> to wp-config.php to
- * disable the display of errors.
+ * WP_DEBUG_DISPLAY and WP_DEBUG_LOG perform no function unless WP_DEBUG is true.
+ * WP_DEBUG defaults defaults to false.
  *
- * Add <code>define('WP_DEBUG_LOG', true);</code> to wp-config.php to log
- * eerrors to debug.log in the wp-content directory.
+ * When WP_DEBUG is true, all PHP notices are reported. WordPress will also display
+ * notices, including one when a deprecated WordPress function, function argument,
+ * or file is used. Deprecated code may be removed from a later version.
+ *
+ * It is strongly recommended that plugin and theme authors use WP_DEBUG for their
+ * development environments.
+ *
+ * When WP_DEBUG_DISPLAY is true, WordPress will force errors to be displayed.
+ * WP_DEBUG_DISPLAY defaults to true. Defining it as false prevents WordPress from
+ * changing the global configuration setting. (Defining WP_DEBUG_DISPLAY as false
+ * will never force errors to be hidden.)
+ *
+ * When WP_DEBUG_LOG is true, errors will be logged to wp-content/debug.log.
+ * WP_DEBUG_LOG defaults to false.
  *
  * @access private
  * @since 3.0.0