#222109 by David_Rothstein: Fix documentation for module_list().

2 files changed, 38 insertions, 25 deletions

diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc
index 84fdd9833..61f473a43 100644
--- a/includes/bootstrap.inc
+++ b/includes/bootstrap.inc
@@ -894,7 +894,12 @@ function drupal_page_is_cacheable($allow_caching = NULL) {
  */
 function bootstrap_invoke_all($hook) {
   // Bootstrap modules should have been loaded when this function is called, so
-  // we don't need to tell module_list() to reset its bootstrap list.
+  // we don't need to tell module_list() to reset its internal list (and we
+  // therefore leave the first parameter at its default value of FALSE). We
+  // still pass in TRUE for the second parameter, though; in case this is the
+  // first time during the bootstrap that module_list() is called, we want to
+  // make sure that its internal cache is primed with the bootstrap modules
+  // only.
   foreach (module_list(FALSE, TRUE) as $module) {
     drupal_load('module', $module);
     module_invoke($module, $hook);
@@ -2651,15 +2656,11 @@ function drupal_get_schema($table = NULL, $rebuild = FALSE) {
       // On some databases this function may be called before bootstrap has
       // been completed, so we force the functions we need to load just in case.
       if (function_exists('module_load_all_includes')) {
-        // There is currently a bug in module_list() where it caches what it
-        // was last called with, which is not always what you want.
-        // module_load_all_includes() calls module_list(), but if this function
-        // is called very early in the bootstrap process then it will be
-        // uninitialized and therefore return no modules. Instead, we have to
-        // "prime" module_list() here to to values we want, specifically
-        // "yes rebuild the list and don't limit to bootstrap".
-        // @todo Remove this call after http://drupal.org/node/222109 is fixed.
-        module_list(TRUE, FALSE);
+        // This function can be called very early in the bootstrap process, so
+        // we force the module_list() cache to be refreshed to ensure that it
+        // contains the complete list of modules before we go on to call
+        // module_load_all_includes().
+        module_list(TRUE);
         module_load_all_includes('install');
       }
 
diff --git a/includes/module.inc b/includes/module.inc
index 8e2ec6158..403b4ea6f 100644
--- a/includes/module.inc
+++ b/includes/module.inc
@@ -32,27 +32,39 @@ function module_load_all($bootstrap = FALSE) {
 
 
 /**
- * Collect a list of all loaded modules. During the bootstrap, return only
- * vital modules. See bootstrap.inc
+ * Returns a list of currently active modules.
+ *
+ * Usually, this returns a list of all enabled modules. When called early on in
+ * the bootstrap, it will return a list of vital modules only (those needed to
+ * generate cached pages).
+ *
+ * All parameters to this function are optional and should generally not be
+ * changed from their defaults.
  *
  * @param $refresh
- *   Whether to force the module list to be regenerated (such as after the
- *   administrator has changed the system settings).
- * @param $bootstrap
- *   Whether to return the reduced set of modules loaded in "bootstrap mode"
- *   for cached pages. See bootstrap.inc.
+ *   (optional) Whether to force the module list to be regenerated (such as
+ *   after the administrator has changed the system settings). Defaults to
+ *   FALSE.
+ * @param $bootstrap_refresh
+ *   (optional) When $refresh is TRUE, setting $bootstrap_refresh to TRUE forces
+ *   the module list to be regenerated using the reduced set of modules loaded
+ *   in "bootstrap mode" for cached pages. Otherwise, setting $refresh to TRUE
+ *   generates the complete list of enabled modules.
  * @param $sort
- *   By default, modules are ordered by weight and module name. Set this option
- *   to TRUE to return a module list ordered only by module name.
+ *   (optional) By default, modules are ordered by weight and module name. Set
+ *   this option to TRUE to return a module list ordered only by module name.
  * @param $fixed_list
- *   (Optional) Override the module list with the given modules. Stays until the
- *   next call with $refresh = TRUE.
+ *   (optional) If an array of module names is provided, this will override the
+ *   module list with the given set of modules. This will persist until the next
+ *   call with $refresh set to TRUE or with a new $fixed_list passed in. This
+ *   parameter is primarily intended for internal use (e.g., in install.php and
+ *   update.php).
  *
  * @return
- *   An associative array whose keys and values are the names of all loaded
- *   modules.
+ *   An associative array whose keys and values are the names of the modules in
+ *   the list.
  */
-function module_list($refresh = FALSE, $bootstrap = FALSE, $sort = FALSE, $fixed_list = NULL) {
+function module_list($refresh = FALSE, $bootstrap_refresh = FALSE, $sort = FALSE, $fixed_list = NULL) {
   static $list = array(), $sorted_list;
 
   if (empty($list) || $refresh || $fixed_list) {
@@ -70,7 +82,7 @@ function module_list($refresh = FALSE, $bootstrap = FALSE, $sort = FALSE, $fixed
         // data.
         drupal_static_reset('system_list');
       }
-      if ($bootstrap) {
+      if ($bootstrap_refresh) {
         $list = system_list('bootstrap');
       }
       else {