From a2868644212724d9b6b00c983d4f35bbd4fd04a4 Mon Sep 17 00:00:00 2001
From: Bob Vincent <bobvin@pillars.net>
Date: Wed, 22 Jun 2011 12:55:55 -0400
Subject: [PATCH] Issue #1136130, followup #2: Add documentation group for "Logging severity levels" and combine redundant documentation blocks.

---
 includes/bootstrap.inc |   72 ++++++++++++++++--------------------------------
 includes/common.inc    |    1 +
 includes/errors.inc    |    2 +
 3 files changed, 27 insertions(+), 48 deletions(-)

diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc
index 231c317487c240718752401225e2b85c7c5f525f..f6a515336d7b0414d1c577acfec6415298d77348 100644
--- a/includes/bootstrap.inc
+++ b/includes/bootstrap.inc
@@ -38,94 +38,70 @@ define('CACHE_PERMANENT', 0);
 define('CACHE_TEMPORARY', -1);
 
 /**
+ * @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.  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.
- *
- * 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_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 8ef79996aac699e5bc4e7891e5bc2d5035eb0c14..4385cdde8fca284a42d4b57e1126a36ba46be43e 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -7045,6 +7045,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 121e069a50aca3dd6f13b174b1fed95aa35e8f37..84e9c77ae2a2609454bf90b5645b7def2b0ead42 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(
-- 
1.7.4.1