Commit 77f6e36f authored by Dries's avatar Dries

- Patch #836748 by aaronbauman, jhodgdon: improve documentation about...

- Patch #836748 by aaronbauman, jhodgdon: improve documentation about install/enable/etc. hook invocation order.
parent a7bbd6d1
......@@ -286,8 +286,25 @@ function module_load_all_includes($type, $name = NULL) {
}
/**
* Enable a given list of modules.
* Enables or installs a given list of modules.
*
* Definitions:
* - "Enabling" is the process of activating a module for use by Drupal.
* - "Disabling" is the process of deactivating a module.
* - "Installing" is the process of enabling it for the first time or after it
* has been uninstalled.
* - "Uninstalling" is the process of removing all traces of a module.
*
* Order of events:
* - Gather and add module dependencies to $module_list (if applicable).
* - For each module that is being enabled:
* - Install module schema and update system registries and caches.
* - If the module is being enabled for the first time or had been
* uninstalled, invoke hook_install() and add it to the list of installed
* modules.
* - Invoke hook_enable().
* - Invoke hook_modules_installed().
* - Invoke hook_modules_enabled().
* @param $module_list
* An array of module names.
* @param $enable_dependencies
......@@ -297,6 +314,11 @@ function module_load_all_includes($type, $name = NULL) {
*
* @return
* FALSE if one or more dependencies are missing, TRUE otherwise.
*
* @see hook_install()
* @see hook_enable()
* @see hook_modules_installed()
* @see hook_modules_enabled()
*/
function module_enable($module_list, $enable_dependencies = TRUE) {
if ($enable_dependencies) {
......
......@@ -2050,15 +2050,18 @@ function hook_flush_caches() {
/**
* Perform necessary actions after modules are installed.
*
* This function differs from hook_install() as it gives all other
* modules a chance to perform actions when a module is installed,
* whereas hook_install() will only be called on the module actually
* being installed.
*
* @see hook_install()
* This function differs from hook_install() in that it gives all other modules
* a chance to perform actions when a module is installed, whereas
* hook_install() is only called on the module actually being installed. See
* module_enable() for a detailed description of the order in which install and
* enable hooks are invoked.
*
* @param $modules
* An array of the installed modules.
*
* @see module_enable()
* @see hook_modules_enabled()
* @see hook_install()
*/
function hook_modules_installed($modules) {
if (in_array('lousy_module', $modules)) {
......@@ -2069,15 +2072,18 @@ function hook_modules_installed($modules) {
/**
* Perform necessary actions after modules are enabled.
*
* This function differs from hook_enable() as it gives all other
* modules a chance to perform actions when modules are enabled,
* whereas hook_enable() will only be called on the module actually
* being enabled.
*
* @see hook_enable()
* This function differs from hook_enable() in that it gives all other modules a
* chance to perform actions when modules are enabled, whereas hook_enable() is
* only called on the module actually being enabled. See module_enable() for a
* detailed description of the order in which install and enable hooks are
* invoked.
*
* @param $modules
* An array of the enabled modules.
*
* @see hook_enable()
* @see hook_modules_installed()
* @see module_enable()
*/
function hook_modules_enabled($modules) {
if (in_array('lousy_module', $modules)) {
......@@ -2089,15 +2095,15 @@ function hook_modules_enabled($modules) {
/**
* Perform necessary actions after modules are disabled.
*
* This function differs from hook_disable() as it gives all other
* modules a chance to perform actions when modules are disabled,
* whereas hook_disable() will only be called on the module actually
* being disabled.
*
* @see hook_disable()
* This function differs from hook_disable() in that it gives all other modules
* a chance to perform actions when modules are disabled, whereas hook_disable()
* is only called on the module actually being disabled.
*
* @param $modules
* An array of the disabled modules.
*
* @see hook_disable()
* @see hook_modules_uninstalled()
*/
function hook_modules_disabled($modules) {
if (in_array('lousy_module', $modules)) {
......@@ -2108,18 +2114,18 @@ function hook_modules_disabled($modules) {
/**
* Perform necessary actions after modules are uninstalled.
*
* This function differs from hook_uninstall() as it gives all other
* modules a chance to perform actions when a module is uninstalled,
* whereas hook_uninstall() will only be called on the module actually
* being uninstalled.
* This function differs from hook_uninstall() in that it gives all other
* modules a chance to perform actions when a module is uninstalled, whereas
* hook_uninstall() is only called on the module actually being uninstalled.
*
* It is recommended that you implement this module if your module
* stores data that may have been set by other modules.
*
* @see hook_uninstall()
*
* @param $modules
* An array of the uninstalled modules.
*
* @see hook_uninstall()
* @see hook_modules_disabled()
*/
function hook_modules_uninstalled($modules) {
foreach ($modules as $module) {
......@@ -2683,11 +2689,11 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* If the module implements hook_schema(), the database tables will
* be created before this hook is fired.
*
* The hook will be called the first time a module is installed, and the
* module's schema version will be set to the module's greatest numbered update
* hook. Because of this, anytime a hook_update_N() is added to the module, this
* function needs to be updated to reflect the current version of the database
* schema.
* This hook will only be called the first time a module is enabled or after it
* is re-enabled after being uninstalled. The module's schema version will be
* set to the module's greatest numbered update hook. Because of this, anytime a
* hook_update_N() is added to the module, this function needs to be updated to
* reflect the current version of the database schema.
*
* See the Schema API documentation at
* @link http://drupal.org/node/146843 http://drupal.org/node/146843 @endlink
......@@ -2701,8 +2707,12 @@ function hook_query_TAG_alter(QueryAlterableInterface $query) {
* Please be sure that anything added or modified in this function that can
* be removed during uninstall should be removed with hook_uninstall().
*
* @see hook_uninstall()
* @see hook_schema()
* @see module_enable()
* @see hook_enable()
* @see hook_disable()
* @see hook_uninstall()
* @see hook_modules_installed()
*/
function hook_install() {
// Populate the default {node_access} record.
......@@ -2910,6 +2920,8 @@ function hook_update_last_removed() {
*
* @see hook_install()
* @see hook_schema()
* @see hook_disable()
* @see hook_modules_uninstalled()
*/
function hook_uninstall() {
variable_del('upload_file_types');
......@@ -2918,7 +2930,11 @@ function hook_uninstall() {
/**
* Perform necessary actions after module is enabled.
*
* The hook is called everytime module is enabled.
* The hook is called every time the module is enabled.
*
* @see module_enable()
* @see hook_install()
* @see hook_modules_enabled()
*/
function hook_enable() {
mymodule_cache_rebuild();
......@@ -2927,7 +2943,10 @@ function hook_enable() {
/**
* Perform necessary actions before module is disabled.
*
* The hook is called everytime module is disabled.
* The hook is called every time the module is disabled.
*
* @see hook_uninstall()
* @see hook_modules_disabled()
*/
function hook_disable() {
mymodule_cache_rebuild();
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment