- Patch #101543 by webchick: document all constants.

8 files changed, 244 insertions, 30 deletions

diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc
index 993b52602..dda784822 100644
--- a/includes/bootstrap.inc
+++ b/includes/bootstrap.inc
@@ -35,19 +35,68 @@ define('CACHE_NORMAL', 1);
 define('CACHE_AGGRESSIVE', 2);
 
 /**
+ * Log message severity -- Emergency: system is unusable.
  *
- * Severity levels, as defined in RFC 3164 http://www.faqs.org/rfcs/rfc3164.html
  * @see watchdog()
  * @see watchdog_severity_levels()
  */
-define('WATCHDOG_EMERG',    0); // Emergency: system is unusable
-define('WATCHDOG_ALERT',    1); // Alert: action must be taken immediately
-define('WATCHDOG_CRITICAL', 2); // Critical: critical conditions
-define('WATCHDOG_ERROR',    3); // Error: error conditions
-define('WATCHDOG_WARNING',  4); // Warning: warning conditions
-define('WATCHDOG_NOTICE',   5); // Notice: normal but significant condition
-define('WATCHDOG_INFO',     6); // Informational: informational messages
-define('WATCHDOG_DEBUG',    7); // Debug: debug-level messages
+define('WATCHDOG_EMERG', 0);
+
+/**
+ * Log message severity -- Alert: action must be taken immediately.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_ALERT', 1);
+
+/**
+ * Log message severity -- Critical: critical conditions.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_CRITICAL', 2);
+
+/**
+ * Log message severity -- Error: error conditions.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_ERROR', 3);
+
+/**
+ * Log message severity -- Warning: warning conditions.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_WARNING', 4);
+
+/**
+ * Log message severity -- Notice: normal but significant condition.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_NOTICE', 5);
+
+/**
+ * Log message severity -- Informational: informational messages.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_INFO', 6);
+
+/**
+ * Log message severity -- Debug: debug-level messages.
+ *
+ * @see watchdog()
+ * @see watchdog_severity_levels()
+ */
+define('WATCHDOG_DEBUG', 7);
 
 /**
  * First bootstrap phase: initialize configuration.
diff --git a/includes/common.inc b/includes/common.inc
index 32b290b4e..598849907 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -3464,10 +3464,12 @@ function drupal_parse_info_file($filename) {
 }
 
 /**
+ * Severity levels, as defined in RFC 3164: http://www.ietf.org/rfc/rfc3164.txt.
+ *
  * @return
  *   Array of the possible severity levels for log messages.
  *
- * @see watchdog
+ * @see watchdog()
  */
 function watchdog_severity_levels() {
   return array(
diff --git a/includes/file.inc b/includes/file.inc
index 0984190ce..a01fad778 100644
--- a/includes/file.inc
+++ b/includes/file.inc
@@ -12,24 +12,62 @@
  * Common file handling functions.
  */
 
+/**
+ * Flag to indicate that the 'public' file download method is enabled.
+ *
+ * When using this method, files are available from a regular HTTP request,
+ * which provides no additional access restrictions.
+ */
 define('FILE_DOWNLOADS_PUBLIC', 1);
+
+/**
+ * Flag to indicate that the 'private' file download method is enabled.
+ *
+ * When using this method, all file requests are served by Drupal, during which
+ * access-control checking can be performed.
+ */
 define('FILE_DOWNLOADS_PRIVATE', 2);
+
+/**
+ * Flag used by file_create_directory() -- create directory if not present.
+ */
 define('FILE_CREATE_DIRECTORY', 1);
+
+/**
+ * Flag used by file_create_directory() -- file permissions may be changed.
+ */
 define('FILE_MODIFY_PERMISSIONS', 2);
+
+/**
+ * Flag for dealing with existing files: Append number until filename is unique.
+ */
 define('FILE_EXISTS_RENAME', 0);
+
+/**
+ * Flag for dealing with existing files: Replace the existing file.
+ */
 define('FILE_EXISTS_REPLACE', 1);
+
+/**
+ * Flag for dealing with existing files: Do nothing and return FALSE.
+ */
 define('FILE_EXISTS_ERROR', 2);
 
 /**
- * A files status can be one of two values: temporary or permanent. The status
- * for each file Drupal manages is stored in the {files} tables. If the status
- * is temporary Drupal's file garbage collection will delete the file and
- * remove it from the files table after a set period of time.
+ * File status -- File has been temporarily saved to the {files} tables.
  *
- * If you wish to add custom statuses for use by contrib modules please expand as
- * binary flags and consider the first 8 bits reserved. (0,1,2,4,8,16,32,64,128)
+ * Drupal's file garbage collection will delete the file and remove it from the
+ * files table after a set period of time.
  */
 define('FILE_STATUS_TEMPORARY', 0);
+
+/**
+ * File status -- File has been permanently saved to the {files} tables.
+ *
+ * If you wish to add custom statuses for use by contrib modules please expand
+ * as binary flags and consider the first 8 bits reserved.
+ * (0,1,2,4,8,16,32,64,128).
+ */
 define('FILE_STATUS_PERMANENT', 1);
 
 /**
diff --git a/includes/install.inc b/includes/install.inc
index 54bfd4bc4..fd68ed9ab 100644
--- a/includes/install.inc
+++ b/includes/install.inc
@@ -1,21 +1,74 @@
 <?php
 // $Id$
 
+/**
+ * Indicates that a module has not been installed yet.
+ */
 define('SCHEMA_UNINSTALLED', -1);
+
+/**
+ * Indicates that a module has been installed.
+ */
 define('SCHEMA_INSTALLED', 0);
 
+/**
+ * Requirement severity -- Informational message only.
+ */
 define('REQUIREMENT_INFO', -1);
+
+/**
+ * Requirement severity -- Requirement successfully met.
+ */
 define('REQUIREMENT_OK', 0);
+
+/**
+ * Requirement severity -- Warning condition; proceed but flag warning.
+ */
 define('REQUIREMENT_WARNING', 1);
+
+/**
+ * Requirement severity -- Error condition; abort installation.
+ */
 define('REQUIREMENT_ERROR', 2);
 
-define('FILE_EXIST',          1);
-define('FILE_READABLE',       2);
-define('FILE_WRITABLE',       4);
-define('FILE_EXECUTABLE',     8);
-define('FILE_NOT_EXIST',      16);
-define('FILE_NOT_READABLE',   32);
-define('FILE_NOT_WRITABLE',   64);
+/**
+ * File permission check -- File exists.
+ */
+define('FILE_EXIST', 1);
+
+/**
+ * File permission check -- File is readable.
+ */
+define('FILE_READABLE', 2);
+
+/**
+ * File permission check -- File is writable.
+ */
+define('FILE_WRITABLE', 4);
+
+/**
+ * File permission check -- File is executable.
+ */
+define('FILE_EXECUTABLE', 8);
+
+/**
+ * File permission check -- File does not exist.
+ */
+define('FILE_NOT_EXIST', 16);
+
+/**
+ * File permission check -- File is not readable.
+ */
+define('FILE_NOT_READABLE', 32);
+
+/**
+ * File permission check -- File is not writable.
+ */
+define('FILE_NOT_WRITABLE', 64);
+
+/**
+ * File permission check -- File is not executable.
+ */
 define('FILE_NOT_EXECUTABLE', 128);
 
 /**
diff --git a/includes/locale.inc b/includes/locale.inc
index 9f51306f9..1937bc904 100644
--- a/includes/locale.inc
+++ b/includes/locale.inc
@@ -3,9 +3,12 @@
 
 /**
  * @file
- *   Administration functions for locale.module.
+ * Administration functions for locale.module.
  */
 
+/**
+ * Regular expression pattern used to localize JavaScript strings.
+ */
 define('LOCALE_JS_STRING', '(?:(?:\'(?:\\\\\'|[^\'])*\'|"(?:\\\\"|[^"])*")(?:\s*\+\s*)?)+');
 
 /**
diff --git a/includes/menu.inc b/includes/menu.inc
index 4e20a7e7a..35faf77dd 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -77,12 +77,39 @@
  * Flags for use in the "type" attribute of menu items.
  */
 
+/**
+ * Internal menu flag -- menu item is the root of the menu tree.
+ */
 define('MENU_IS_ROOT', 0x0001);
+
+/**
+ * Internal menu flag -- menu item is visible in the menu tree.
+ */
 define('MENU_VISIBLE_IN_TREE', 0x0002);
+
+/**
+ * Internal menu flag -- menu item is visible in the breadcrumb.
+ */
 define('MENU_VISIBLE_IN_BREADCRUMB', 0x0004);
+
+/**
+ * Internal menu flag -- menu item links back to its parnet.
+ */
 define('MENU_LINKS_TO_PARENT', 0x0008);
+
+/**
+ * Internal menu flag -- menu item can be modified by administrator.
+ */
 define('MENU_MODIFIED_BY_ADMIN', 0x0020);
+
+/**
+ * Internal menu flag -- menu item was created by administrator.
+ */
 define('MENU_CREATED_BY_ADMIN', 0x0040);
+
+/**
+ * Internal menu flag -- menu item is a local task.
+ */
 define('MENU_IS_LOCAL_TASK', 0x0080);
 
 /**
@@ -97,6 +124,8 @@ define('MENU_IS_LOCAL_TASK', 0x0080);
  */
 
 /**
+ * Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.
+ *
  * Normal menu items show up in the menu tree and can be moved/hidden by
  * the administrator. Use this for most menu items. It is the default value if
  * no menu item type is specified.
@@ -104,12 +133,16 @@ define('MENU_IS_LOCAL_TASK', 0x0080);
 define('MENU_NORMAL_ITEM', MENU_VISIBLE_IN_TREE | MENU_VISIBLE_IN_BREADCRUMB);
 
 /**
+ * Menu type -- A hidden, internal callback, typically used for API calls.
+ *
  * Callbacks simply register a path so that the correct function is fired
  * when the URL is accessed. They are not shown in the menu.
  */
 define('MENU_CALLBACK', MENU_VISIBLE_IN_BREADCRUMB);
 
 /**
+ * Menu type -- A normal menu item, hidden until enabled by an administrator.
+ *
  * Modules may "suggest" menu items that the administrator may enable. They act
  * just as callbacks do until enabled, at which time they act like normal items.
  * Note for the value: 0x0010 was a flag which is no longer used, but this way
@@ -118,13 +151,17 @@ define('MENU_CALLBACK', MENU_VISIBLE_IN_BREADCRUMB);
 define('MENU_SUGGESTED_ITEM', MENU_VISIBLE_IN_BREADCRUMB | 0x0010);
 
 /**
- * Local tasks are rendered as tabs by default. Use this for menu items that
- * describe actions to be performed on their parent item. An example is the path
- * "node/52/edit", which performs the "edit" task on "node/52".
+ * Menu type -- A task specific to the parent item, usually rendered as a tab.
+ *
+ * Local tasks are menu items that describe actions to be performed on their
+ * parent item. An example is the path "node/52/edit", which performs the
+ * "edit" task on "node/52".
  */
 define('MENU_LOCAL_TASK', MENU_IS_LOCAL_TASK);
 
 /**
+ * Menu type -- The "default" local task, which is initially active.
+ *
  * Every set of local tasks should provide one "default" task, that links to the
  * same path as its parent when clicked.
  */
@@ -140,9 +177,24 @@ define('MENU_DEFAULT_LOCAL_TASK', MENU_IS_LOCAL_TASK | MENU_LINKS_TO_PARENT);
  * Status codes for menu callbacks.
  */
 
+/**
+ * Internal menu status code -- Menu item was found.
+ */
 define('MENU_FOUND', 1);
+
+/**
+ * Internal menu status code -- Menu item was not found.
+ */
 define('MENU_NOT_FOUND', 2);
+
+/**
+ * Internal menu status code -- Menu item access is denied.
+ */
 define('MENU_ACCESS_DENIED', 3);
+
+/**
+ * Internal menu status code -- Menu item inaccessible because site is offline.
+ */
 define('MENU_SITE_OFFLINE', 4);
 
 /**
diff --git a/includes/password.inc b/includes/password.inc
index 6c145cf9e..d5dccc398 100644
--- a/includes/password.inc
+++ b/includes/password.inc
@@ -22,9 +22,13 @@
 define('DRUPAL_HASH_COUNT', 14);
 
 /**
- * The min and max allowed log2 number of iterations for password stretching.
+ * The minimum allowed log2 number of iterations for password stretching.
  */
 define('DRUPAL_MIN_HASH_COUNT', 7);
+
+/**
+ * The maximum allowed log2 number of iterations for password stretching.
+ */
 define('DRUPAL_MAX_HASH_COUNT', 30);
 
 /**
diff --git a/includes/theme.inc b/includes/theme.inc
index 15d4429e0..07ec0786b 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -18,9 +18,22 @@
  * Markers used by theme_mark() and node_mark() to designate content.
  * @see theme_mark(), node_mark()
  */
-define('MARK_READ',    0);
-define('MARK_NEW',     1);
+
+/**
+ * Mark content as read.
+ */
+define('MARK_READ', 0);
+
+/**
+ * Mark content as being new.
+ */
+define('MARK_NEW', 1);
+
+/**
+ * Mark content as being updated.
+ */
 define('MARK_UPDATED', 2);
+
 /**
  * @} End of "Content markers".
  */