Issue #1136130 follow-up by pillarsdotnet: Document why WATCHDOG_* constants are necessary.

5 files changed, 28 insertions, 45 deletions

diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc
index fd4c0408a..02af930dd 100644
--- a/includes/bootstrap.inc
+++ b/includes/bootstrap.inc
@@ -38,94 +38,70 @@ define('CACHE_PERMANENT', 0);
 define('CACHE_TEMPORARY', -1);
 
 /**
- * Log message severity -- Emergency: system is unusable.
+ * @defgroup logging_severity_levels Logging severity levels
+ * @{
+ * Logging severity levels as defined in RFC 3164.
  *
  * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
+ * defined in RFC 3164, section 4.1.1.  PHP supplies predefined LOG_* constants
+ * for use in the syslog() function, but their values on Windows builds do not
+ * correspond to RFC 3164.  The associated PHP bug report was closed with the
+ * comment, "And it's also not a bug, as Windows just have less log levels,"
+ * and "So the behavior you're seeing is perfectly normal."
+ *
+ * @see http://www.faqs.org/rfcs/rfc3164.html
+ * @see http://bugs.php.net/bug.php?id=18090
+ * @see http://php.net/manual/function.syslog.php
+ * @see http://php.net/manual/network.constants.php
  * @see watchdog()
  * @see watchdog_severity_levels()
  */
+
+/**
+ * Log message severity -- Emergency: system is unusable.
+ */
 define('WATCHDOG_EMERGENCY', 0);
 
 /**
  * Log message severity -- Alert: action must be taken immediately.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_ALERT', 1);
 
 /**
  * Log message severity -- Critical: critical conditions.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_CRITICAL', 2);
 
 /**
  * Log message severity -- Error: error conditions.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_ERROR', 3);
 
 /**
  * Log message severity -- Warning: warning conditions.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_WARNING', 4);
 
 /**
  * Log message severity -- Notice: normal but significant condition.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_NOTICE', 5);
 
 /**
  * Log message severity -- Informational: informational messages.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_INFO', 6);
 
 /**
  * Log message severity -- Debug: debug-level messages.
- *
- * The WATCHDOG_* constant definitions correspond to the logging severity levels
- * defined in RFC 3164, section 4.1.1: http://www.faqs.org/rfcs/rfc3164.html
- *
- * @see watchdog()
- * @see watchdog_severity_levels()
  */
 define('WATCHDOG_DEBUG', 7);
 
 /**
+ * @} End of "defgroup logging_severity_levels".
+ */
+
+/**
  * First bootstrap phase: initialize configuration.
  */
 define('DRUPAL_BOOTSTRAP_CONFIGURATION', 0);
diff --git a/includes/common.inc b/includes/common.inc
index a2768a51e..97c32a078 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -7049,6 +7049,7 @@ function drupal_parse_info_format($data) {
  *   Array of the possible severity levels for log messages.
  *
  * @see watchdog()
+ * @ingroup logging_severity_levels
  */
 function watchdog_severity_levels() {
   return array(
diff --git a/includes/errors.inc b/includes/errors.inc
index be7242856..bd31bebed 100644
--- a/includes/errors.inc
+++ b/includes/errors.inc
@@ -24,6 +24,8 @@ define('ERROR_REPORTING_DISPLAY_ALL', 2);
  * Map PHP error constants to watchdog severity levels.
  * The error constants are documented at
  * http://php.net/manual/en/errorfunc.constants.php
+ *
+ * @ingroup logging_severity_levels
  */
 function drupal_error_levels() {
   $types = array(
diff --git a/modules/dblog/dblog.admin.inc b/modules/dblog/dblog.admin.inc
index 963e6f8eb..0655e7564 100644
--- a/modules/dblog/dblog.admin.inc
+++ b/modules/dblog/dblog.admin.inc
@@ -10,6 +10,8 @@
  *
  * Messages are truncated at 56 chars. Full-length message could be viewed at
  * the message details page.
+ *
+ * @ingroup logging_severity_levels
  */
 function dblog_overview() {
   $filter = dblog_build_filter_query();
diff --git a/modules/dblog/dblog.test b/modules/dblog/dblog.test
index 5717455ef..ca844a361 100644
--- a/modules/dblog/dblog.test
+++ b/modules/dblog/dblog.test
@@ -528,6 +528,8 @@ class DBLogTestCase extends DrupalWebTestCase {
    *   CSS class attribute.
    * @return
    *   The watchdog severity constant or NULL if not found.
+   *
+   * @ingroup logging_severity_levels
    */
   protected function getSeverityConstant($class) {
     // Reversed array from dblog_overview().