summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJennifer Hodgdon2012-10-04 16:04:02 (GMT)
committer Jennifer Hodgdon2012-10-04 16:04:02 (GMT)
commit0a1b3116cae3577f966a8c86233c321d98c699e4 (patch)
tree4b81c649dd5793c35684dc8ce23acd78bb4c5327
parentdb5bfb425a0571c2bc6fe164bc2fea4df60065e4 (diff)
Issue #1317626 by Albert Volkman, xjm: Clean up API docs for include files H-M
-rw-r--r--includes/image.inc19
-rw-r--r--includes/install.core.inc69
-rw-r--r--includes/install.inc49
-rw-r--r--includes/language.inc6
-rw-r--r--includes/mail.inc25
-rw-r--r--includes/menu.inc136
-rw-r--r--includes/module.inc33
7 files changed, 180 insertions, 157 deletions
diff --git a/includes/image.inc b/includes/image.inc
index f6ae7f1..ee5a086 100644
--- a/includes/image.inc
+++ b/includes/image.inc
@@ -34,7 +34,7 @@
*/
/**
- * Return a list of available toolkits.
+ * Gets a list of available toolkits.
*
* @return
* An array with the toolkit names as keys and the descriptions as values.
@@ -55,7 +55,7 @@ function image_get_available_toolkits() {
}
/**
- * Retrieve the name of the currently used toolkit.
+ * Gets the name of the currently used toolkit.
*
* @return
* String containing the name of the selected toolkit, or FALSE on error.
@@ -101,7 +101,7 @@ function image_toolkit_invoke($method, stdClass $image, array $params = array())
}
/**
- * Get details about an image.
+ * Gets details about an image.
*
* Drupal supports GIF, JPG and PNG file formats when used with the GD
* toolkit, and may support others, depending on which toolkits are
@@ -261,7 +261,7 @@ function image_scale(stdClass $image, $width = NULL, $height = NULL, $upscale =
}
/**
- * Resize an image to the given dimensions (ignoring aspect ratio).
+ * Resizes an image to the given dimensions (ignoring aspect ratio).
*
* @param $image
* An image object returned by image_load().
@@ -284,7 +284,7 @@ function image_resize(stdClass $image, $width, $height) {
}
/**
- * Rotate an image by the given number of degrees.
+ * Rotates an image by the given number of degrees.
*
* @param $image
* An image object returned by image_load().
@@ -308,7 +308,7 @@ function image_rotate(stdClass $image, $degrees, $background = NULL) {
}
/**
- * Crop an image to the rectangle specified by the given rectangle.
+ * Crops an image to a rectangle specified by the given dimensions.
*
* @param $image
* An image object returned by image_load().
@@ -340,7 +340,7 @@ function image_crop(stdClass $image, $x, $y, $width, $height) {
}
/**
- * Convert an image to grayscale.
+ * Converts an image to grayscale.
*
* @param $image
* An image object returned by image_load().
@@ -355,9 +355,8 @@ function image_desaturate(stdClass $image) {
return image_toolkit_invoke('desaturate', $image);
}
-
/**
- * Load an image file and return an image object.
+ * Loads an image file and returns an image object.
*
* Any changes to the file are not saved until image_save() is called.
*
@@ -400,7 +399,7 @@ function image_load($file, $toolkit = FALSE) {
}
/**
- * Close the image and save the changes to a file.
+ * Closes the image and saves the changes to a file.
*
* @param $image
* An image object returned by image_load(). The object's 'info' property
diff --git a/includes/install.core.inc b/includes/install.core.inc
index fc37de1..bba8ce0 100644
--- a/includes/install.core.inc
+++ b/includes/install.core.inc
@@ -6,8 +6,7 @@
*/
/**
- * Global flag to indicate that a task should not be run during the current
- * installation request.
+ * Do not run the task during the current installation request.
*
* This can be used to skip running an installation task when certain
* conditions are met, even though the task may still show on the list of
@@ -20,8 +19,7 @@
define('INSTALL_TASK_SKIP', 1);
/**
- * Global flag to indicate that a task should be run on each installation
- * request that reaches it.
+ * Run the task on each installation request until the database is set up.
*
* This is primarily used by the Drupal installer for bootstrap-related tasks.
*/
@@ -200,7 +198,7 @@ function install_state_defaults() {
}
/**
- * Begin an installation request, modifying the installation state as needed.
+ * Begins an installation request, modifying the installation state as needed.
*
* This function performs commands that must run at the beginning of every page
* request. It throws an exception if the installation should not proceed.
@@ -709,7 +707,7 @@ function install_display_output($output, $install_state) {
}
/**
- * Installation task; verify the requirements for installing Drupal.
+ * Verifies the requirements for installing Drupal.
*
* @param $install_state
* An array of information about the current installation state.
@@ -786,7 +784,7 @@ function install_system_module(&$install_state) {
}
/**
- * Verify and return the last installation task that was completed.
+ * Verifies and returns the last installation task that was completed.
*
* @return
* The last completed task, if there is one. An exception is thrown if Drupal
@@ -830,7 +828,7 @@ function install_verify_settings() {
}
/**
- * Verify PDO library.
+ * Verifies the PDO library.
*/
function install_verify_pdo() {
// PDO was moved to PHP core in 5.2.0, but the old extension (targeting 5.0
@@ -842,15 +840,13 @@ function install_verify_pdo() {
}
/**
- * Installation task; define a form to configure and rewrite settings.php.
+ * Form constructor for a form to configure and rewrite settings.php.
*
- * @param $form_state
- * An associative array containing the current state of the form.
* @param $install_state
* An array of information about the current installation state.
*
- * @return
- * The form API definition for the database configuration form.
+ * @see install_settings_form_validate()
+ * @see install_settings_form_submit()
*/
function install_settings_form($form, &$form_state, &$install_state) {
global $databases;
@@ -913,7 +909,9 @@ function install_settings_form($form, &$form_state, &$install_state) {
}
/**
- * Form API validate for install_settings form.
+ * Form validation handler for install_settings_form().
+ *
+ * @see install_settings_form_submit()
*/
function install_settings_form_validate($form, &$form_state) {
$driver = $form_state['values']['driver'];
@@ -970,7 +968,9 @@ function install_database_errors($database, $settings_file) {
}
/**
- * Form API submit for install_settings form.
+ * Form submission handler for install_settings_form().
+ *
+ * @see install_settings_form_validate()
*/
function install_settings_form_submit($form, &$form_state) {
global $install_state;
@@ -1001,7 +1001,7 @@ function install_find_profiles() {
}
/**
- * Installation task; select which profile to install.
+ * Selects which profile to install.
*
* @param $install_state
* An array of information about the current installation state. The chosen
@@ -1041,8 +1041,7 @@ function install_select_profile(&$install_state) {
}
/**
- * Helper function for automatically selecting an installation profile from a
- * list or from a selection passed in via $_POST.
+ * Selects an installation profile from a list or from a $_POST submission.
*/
function _install_select_profile($profiles) {
if (sizeof($profiles) == 0) {
@@ -1065,7 +1064,7 @@ function _install_select_profile($profiles) {
}
/**
- * Form API array definition for the profile selection form.
+ * Form constructor for the profile selection form.
*
* @param $form_state
* Array of metadata about state of form processing.
@@ -1297,7 +1296,7 @@ function install_already_done_error() {
}
/**
- * Installation task; load information about the chosen profile.
+ * Loads information about the chosen profile during installation.
*
* @param $install_state
* An array of information about the current installation state. The loaded
@@ -1316,7 +1315,7 @@ function install_load_profile(&$install_state) {
}
/**
- * Installation task; perform a full bootstrap of Drupal.
+ * Performs a full bootstrap of Drupal during installation.
*
* @param $install_state
* An array of information about the current installation state.
@@ -1326,7 +1325,7 @@ function install_bootstrap_full(&$install_state) {
}
/**
- * Installation task; install required modules via a batch process.
+ * Installs required modules via a batch process.
*
* @param $install_state
* An array of information about the current installation state.
@@ -1379,7 +1378,7 @@ function install_profile_modules(&$install_state) {
}
/**
- * Installation task; import languages via a batch process.
+ * Imports languages via a batch process during installation.
*
* @param $install_state
* An array of information about the current installation state.
@@ -1413,15 +1412,13 @@ function install_import_locales(&$install_state) {
}
/**
- * Installation task; configure settings for the new site.
+ * Form constructor for a form to configure the new site.
*
- * @param $form_state
- * An associative array containing the current state of the form.
* @param $install_state
* An array of information about the current installation state.
*
- * @return
- * The form API definition for the site configuration form.
+ * @see install_configure_form_validate()
+ * @see install_configure_form_submit()
*/
function install_configure_form($form, &$form_state, &$install_state) {
drupal_set_title(st('Configure site'));
@@ -1487,7 +1484,7 @@ function install_import_locales_remaining(&$install_state) {
}
/**
- * Installation task; perform final steps and display a 'finished' page.
+ * Finishes importing files at end of installation.
*
* @param $install_state
* An array of information about the current installation state.
@@ -1674,7 +1671,11 @@ function install_check_requirements($install_state) {
}
/**
- * Form API array definition for site configuration.
+ * Returns a Form API array definition for site configuration.
+ *
+ * @see install_configure_form()
+ * @see install_configure_form_validate()
+ * @see install_configure_form_submit()
*/
function _install_configure_form($form, &$form_state, &$install_state) {
include_once DRUPAL_ROOT . '/includes/locale.inc';
@@ -1787,7 +1788,9 @@ function _install_configure_form($form, &$form_state, &$install_state) {
}
/**
- * Form API validate for the site configuration form.
+ * Form validation handler for install_configure_form().
+ *
+ * @see install_configure_form_submit()
*/
function install_configure_form_validate($form, &$form_state) {
if ($error = user_validate_name($form_state['values']['account']['name'])) {
@@ -1802,7 +1805,9 @@ function install_configure_form_validate($form, &$form_state) {
}
/**
- * Form API submit for the site configuration form.
+ * Form submission handler for install_configure_form().
+ *
+ * @see install_configure_form_validate()
*/
function install_configure_form_submit($form, &$form_state) {
global $user;
diff --git a/includes/install.inc b/includes/install.inc
index 6411f8f..2f50c85 100644
--- a/includes/install.inc
+++ b/includes/install.inc
@@ -1,6 +1,11 @@
<?php
/**
+* @file
+* API functions for installing modules and themes.
+*/
+
+/**
* Indicates that a module has not been installed yet.
*/
define('SCHEMA_UNINSTALLED', -1);
@@ -71,7 +76,7 @@ define('FILE_NOT_WRITABLE', 64);
define('FILE_NOT_EXECUTABLE', 128);
/**
- * Initialize the update system by loading all installed module's .install files.
+ * Loads .install files for installed modules to initialize the update system.
*/
function drupal_load_updates() {
foreach (drupal_get_installed_schema_version(NULL, FALSE, TRUE) as $module => $schema_version) {
@@ -204,11 +209,12 @@ function drupal_install_profile_distribution_name() {
}
/**
- * Auto detect the base_url with PHP predefined variables.
+ * Detects the base URL using the PHP $_SERVER variables.
*
* @param $file
* The name of the file calling this function so we can strip it out of
* the URI when generating the base_url.
+ *
* @return
* The auto-detected $base_url that should be configured in settings.php
*/
@@ -223,7 +229,7 @@ function drupal_detect_baseurl($file = 'install.php') {
}
/**
- * Detect all supported databases that are compiled into PHP.
+ * Detects all supported databases that are compiled into PHP.
*
* @return
* An array of database types compiled into PHP.
@@ -239,7 +245,7 @@ function drupal_detect_database_types() {
}
/**
- * Return all supported database installer objects that are compiled into PHP.
+ * Returns all supported database installer objects that are compiled into PHP.
*
* @return
* An array of database installer objects compiled into PHP.
@@ -576,7 +582,7 @@ class DatabaseTaskException extends Exception {
}
/**
- * Replace values in settings.php with values in the submitted array.
+ * Replaces values in settings.php with values in the submitted array.
*
* @param $settings
* An array of settings that need to be updated.
@@ -654,10 +660,11 @@ function drupal_rewrite_settings($settings = array(), $prefix = '') {
}
/**
- * Verify an install profile for installation.
+ * Verifies an install profile for installation.
*
* @param $install_state
* An array of information about the current installation state.
+ *
* @return
* The list of modules to install.
*/
@@ -706,7 +713,7 @@ function drupal_verify_profile($install_state) {
}
/**
- * Callback to install the system module.
+ * Installs the system module.
*
* Separated from the installation of other modules so core system
* functions can be made available while other modules are installed.
@@ -800,7 +807,7 @@ function drupal_uninstall_modules($module_list = array(), $uninstall_dependents
}
/**
- * Verify the state of the specified file.
+ * Verifies the state of the specified file.
*
* @param $file
* The file to check for.
@@ -808,6 +815,7 @@ function drupal_uninstall_modules($module_list = array(), $uninstall_dependents
* An optional bitmask created from various FILE_* constants.
* @param $type
* The type of file. Can be file (default), dir, or link.
+ *
* @return
* TRUE on success or FALSE on failure. A message is set for the latter.
*/
@@ -879,7 +887,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') {
}
/**
- * Create a directory with specified permissions.
+ * Creates a directory with the specified permissions.
*
* @param $file
* The name of the directory to create;
@@ -887,6 +895,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') {
* The permissions of the directory to create.
* @param $message
* (optional) Whether to output messages. Defaults to TRUE.
+ *
* @return
* TRUE/FALSE whether or not the directory was successfully created.
*/
@@ -918,7 +927,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) {
}
/**
- * Attempt to fix file permissions.
+ * Attempts to fix file permissions.
*
* The general approach here is that, because we do not know the security
* setup of the webserver, we apply our permission changes to all three
@@ -935,6 +944,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) {
* The desired permissions for the file.
* @param $message
* (optional) Whether to output messages. Defaults to TRUE.
+ *
* @return
* TRUE/FALSE whether or not we were able to fix the file's permissions.
*/
@@ -1000,7 +1010,7 @@ function drupal_install_fix_file($file, $mask, $message = TRUE) {
}
/**
- * Send the user to a different installer page.
+ * Sends the user to a different installer page.
*
* This issues an on-site HTTP redirect. Messages (and errors) are erased.
*
@@ -1078,7 +1088,7 @@ function drupal_requirements_url($severity) {
}
/**
- * Functional equivalent of t(), used when some systems are not available.
+ * Translates a string when some systems are not available.
*
* Used during the install process, when database, theme, and localization
* system is possibly not yet available.
@@ -1138,7 +1148,7 @@ function st($string, array $args = array(), array $options = array()) {
}
/**
- * Check an install profile's requirements.
+ * Checks an install profile's requirements.
*
* @param $profile
* Name of install profile to check.
@@ -1169,11 +1179,12 @@ function drupal_check_profile($profile) {
}
/**
- * Extract highest severity from requirements array.
+ * Extracts the highest severity from the requirements array.
*
* @param $requirements
* An array of requirements, in the same format as is returned by
* hook_requirements().
+ *
* @return
* The highest severity in the array.
*/
@@ -1188,12 +1199,13 @@ function drupal_requirements_severity(&$requirements) {
}
/**
- * Check a module's requirements.
+ * Checks a module's requirements.
*
* @param $module
* Machine name of module to check.
+ *
* @return
- * TRUE/FALSE depending on the requirements are in place.
+ * TRUE or FALSE, depending on whether the requirements are met.
*/
function drupal_check_module($module) {
module_load_install($module);
@@ -1218,13 +1230,14 @@ function drupal_check_module($module) {
}
/**
- * Retrieve info about an install profile from its .info file.
+ * Retrieves information about an install profile from its .info file.
*
* The information stored in a profile .info file is similar to that stored in
* a normal Drupal module .info file. For example:
* - name: The real name of the install profile for display purposes.
* - description: A brief description of the profile.
- * - dependencies: An array of shortnames of other modules this install profile requires.
+ * - dependencies: An array of shortnames of other modules that this install
+ * profile requires.
*
* Additional, less commonly-used information that can appear in a profile.info
* file but not in a normal Drupal module .info file includes:
diff --git a/includes/language.inc b/includes/language.inc
index c530c2a..d0ea831 100644
--- a/includes/language.inc
+++ b/includes/language.inc
@@ -419,7 +419,7 @@ function language_from_default() {
}
/**
- * Split the given path into prefix and actual path.
+ * Splits the given path into prefix and actual path.
*
* Parse the given path and return the language object identified by the
* prefix and the actual path.
@@ -451,10 +451,10 @@ function language_url_split_prefix($path, $languages) {
}
/**
- * Return the possible fallback languages ordered by language weight.
+ * Returns the possible fallback languages ordered by language weight.
*
* @param
- * The language type.
+ * (optional) The language type. Defaults to LANGUAGE_TYPE_CONTENT.
*
* @return
* An array of language codes.
diff --git a/includes/mail.inc b/includes/mail.inc
index 13a6f46..e309372 100644
--- a/includes/mail.inc
+++ b/includes/mail.inc
@@ -13,7 +13,7 @@
define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER_SOFTWARE'], 'Win32') !== FALSE ? "\r\n" : "\n");
/**
- * Compose and optionally send an e-mail message.
+ * Composes and optionally sends an e-mail message.
*
* Sending an e-mail works with defining an e-mail template (subject, text
* and possibly e-mail headers) and the replacement values to use in the
@@ -191,7 +191,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N
}
/**
- * Returns an object that implements the MailSystemInterface.
+ * Returns an object that implements the MailSystemInterface interface.
*
* Allows for one or more custom mail backends to format and send mail messages
* composed using drupal_mail().
@@ -328,7 +328,7 @@ interface MailSystemInterface {
}
/**
- * Perform format=flowed soft wrapping for mail (RFC 3676).
+ * Performs format=flowed soft wrapping for mail (RFC 3676).
*
* We use delsp=yes wrapping, but only break non-spaced languages when
* absolutely necessary to avoid compatibility issues.
@@ -371,8 +371,7 @@ function drupal_wrap_mail($text, $indent = '') {
}
/**
- * Transform an HTML string into plain text, preserving the structure of the
- * markup. Useful for preparing the body of a node to be sent by e-mail.
+ * Transforms an HTML string into plain text, preserving its structure.
*
* The output will be suitable for use as 'format=flowed; delsp=yes' text
* (RFC 3676) and can be passed directly to drupal_mail() for sending.
@@ -551,9 +550,9 @@ function drupal_html_to_text($string, $allowed_tags = NULL) {
}
/**
- * Helper function for array_walk in drupal_wrap_mail().
- *
* Wraps words on a single line.
+ *
+ * Callback for array_walk() winthin drupal_wrap_mail().
*/
function _drupal_wrap_mail_line(&$line, $key, $values) {
// Use soft-breaks only for purely quoted or unindented text.
@@ -563,9 +562,9 @@ function _drupal_wrap_mail_line(&$line, $key, $values) {
}
/**
- * Helper function for drupal_html_to_text().
- *
* Keeps track of URLs and replaces them with placeholder tokens.
+ *
+ * Callback for preg_replace_callback() within drupal_html_to_text().
*/
function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) {
global $base_url, $base_path;
@@ -590,18 +589,18 @@ function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) {
}
/**
- * Helper function for drupal_wrap_mail() and drupal_html_to_text().
+ * Replaces non-quotation markers from a given piece of indentation with spaces.
*
- * Replace all non-quotation markers from a given piece of indentation with spaces.
+ * Callback for array_map() within drupal_html_to_text().
*/
function _drupal_html_to_text_clean($indent) {
return preg_replace('/[^>]/', ' ', $indent);
}
/**
- * Helper function for drupal_html_to_text().
+ * Pads the last line with the given character.
*
- * Pad the last line with the given character.
+ * @see drupal_html_to_text()
*/
function _drupal_html_to_text_pad($text, $pad, $prefix = '') {
// Remove last line break.
diff --git a/includes/menu.inc b/includes/menu.inc
index b25a374..31e9a7e 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -417,9 +417,9 @@ function menu_unserialize($data, $map) {
* @param $path
* The path.
* @param $router_item
- * The router item. Usually you take a router entry from menu_get_item and
- * set it back either modified or to a different path. This lets you modify the
- * navigation block, the page title, the breadcrumb and the page help in one
+ * The router item. Usually a router entry from menu_get_item() is either
+ * modified or set to a different path. This allows the navigation block,
+ * the page title, the breadcrumb, and the page help to be modified in one
* call.
*/
function menu_set_item($path, $router_item) {
@@ -427,7 +427,7 @@ function menu_set_item($path, $router_item) {
}
/**
- * Get a router item.
+ * Gets a router item.
*
* @param $path
* The path, for example node/5. The function will find the corresponding
@@ -606,7 +606,7 @@ function _menu_load_objects(&$item, &$map) {
}
/**
- * Check access to a menu item using the access callback
+ * Checks access to a menu item using the access callback
*
* @param $item
* A menu router or menu link item
@@ -638,7 +638,7 @@ function _menu_check_access(&$item, $map) {
}
/**
- * Localize the router item title using t() or another callback.
+ * Localizes the router item title using t() or another callback.
*
* Translate the title and description to allow storage of English title
* strings in the database, yet display of them in the language required
@@ -796,14 +796,14 @@ function _menu_translate(&$router_item, $map, $to_arg = FALSE) {
}
/**
- * This function translates the path elements in the map using any to_arg
- * helper function. These functions take an argument and return an object.
- * See http://drupal.org/node/109153 for more information.
+ * Translates the path elements in the map using any to_arg helper function.
*
* @param $map
* An array of path arguments (ex: array('node', '5'))
* @param $to_arg_functions
* An array of helper function (ex: array(2 => 'menu_tail_to_arg'))
+ *
+ * @see hook_menu()
*/
function _menu_link_map_translate(&$map, $to_arg_functions) {
$to_arg_functions = unserialize($to_arg_functions);
@@ -820,14 +820,14 @@ function _menu_link_map_translate(&$map, $to_arg_functions) {
}
/**
- * Returns path as one string from the argument we are currently at.
+ * Returns a string containing the path relative to the current index.
*/
function menu_tail_to_arg($arg, $map, $index) {
return implode('/', array_slice($map, $index));
}
/**
- * Loads path as one string from the argument we are currently at.
+ * Loads the path as one string relative to the current index.
*
* To use this load function, you must specify the load arguments
* in the router item as:
@@ -844,8 +844,10 @@ function menu_tail_load($arg, &$map, $index) {
}
/**
- * This function is similar to _menu_translate() but does link-specific
- * preparation such as always calling to_arg functions
+ * Provides menu link access control, translation, and argument handling.
+ *
+ * This function is similar to _menu_translate(), but it also does
+ * link-specific preparation (such as always calling to_arg() functions).
*
* @param $item
* A menu link.
@@ -939,7 +941,7 @@ function _menu_link_translate(&$item, $translate = FALSE) {
}
/**
- * Get a loaded object from a router item.
+ * Gets a loaded object from a router item.
*
* menu_get_object() provides access to objects loaded by the current router
* item. For example, on the page node/%node, the router loads the %node object,
@@ -1079,7 +1081,7 @@ function menu_tree_output($tree) {
}
/**
- * Get the data structure representing a named menu tree.
+ * Gets the data structure representing a named menu tree.
*
* Since this can be the full tree including hidden items, the data returned
* may be used for generating an an admin interface or a select.
@@ -1147,7 +1149,7 @@ function menu_tree_all_data($menu_name, $link = NULL, $max_depth = NULL) {
}
/**
- * Set the path for determining the active trail of the specified menu tree.
+ * Sets the path for determining the active trail of the specified menu tree.
*
* This path will also affect the breadcrumbs under some circumstances.
* Breadcrumbs are built using the preferred link returned by
@@ -1172,7 +1174,7 @@ function menu_tree_set_path($menu_name, $path = NULL) {
}
/**
- * Get the path for determining the active trail of the specified menu tree.
+ * Gets the path for determining the active trail of the specified menu tree.
*
* @param $menu_name
* The menu name of the requested tree.
@@ -1186,7 +1188,7 @@ function menu_tree_get_path($menu_name) {
}
/**
- * Get the data structure representing a named menu tree, based on the current page.
+ * Gets the data structure for a named menu tree, based on the current page.
*
* The tree order is maintained by storing each parent in an individual
* field, see http://drupal.org/node/141866 for more.
@@ -1320,7 +1322,7 @@ function menu_tree_page_data($menu_name, $max_depth = NULL, $only_active_trail =
}
/**
- * Build a menu tree, translate links, and check access.
+ * Builds a menu tree, translates links, and checks access.
*
* @param $menu_name
* The name of the menu.
@@ -1335,8 +1337,8 @@ function menu_tree_page_data($menu_name, $max_depth = NULL, $only_active_trail =
* trail. This option is ignored, if 'expanded' is non-empty. Internally
* used for breadcrumbs.
* - min_depth: The minimum depth of menu links in the resulting tree.
- * Defaults to 1, which is the default to build a whole tree for a menu, i.e.
- * excluding menu container itself.
+ * Defaults to 1, which is the default to build a whole tree for a menu
+ * (excluding menu container itself).
* - max_depth: The maximum depth of menu links in the resulting tree.
* - conditions: An associative array of custom database select query
* condition key/value pairs; see _menu_build_tree() for the actual query.
@@ -1353,7 +1355,7 @@ function menu_build_tree($menu_name, array $parameters = array()) {
}
/**
- * Build a menu tree.
+ * Builds a menu tree.
*
* This function may be used build the data for a menu tree only, for example
* to further massage the data manually before further processing happens.
@@ -1449,7 +1451,7 @@ function _menu_build_tree($menu_name, array $parameters = array()) {
}
/**
- * Recursive helper function - collect node links.
+ * Collects node links from a given menu tree recursively.
*
* @param $tree
* The menu tree you wish to collect node links from.
@@ -1472,7 +1474,7 @@ function menu_tree_collect_node_links(&$tree, &$node_links) {
}
/**
- * Check access and perform other dynamic operations for each link in the tree.
+ * Checks access and performs dynamic operations for each link in the tree.
*
* @param $tree
* The menu tree you wish to operate on.
@@ -1499,7 +1501,7 @@ function menu_tree_check_access(&$tree, $node_links = array()) {
}
/**
- * Recursive helper function for menu_tree_check_access()
+ * Sorts the menu tree and recursively checks access for each item.
*/
function _menu_tree_check_access(&$tree) {
$new_tree = array();
@@ -1522,7 +1524,7 @@ function _menu_tree_check_access(&$tree) {
}
/**
- * Builds the data representing a menu tree.
+ * Sorts and returns the built data representing a menu tree.
*
* @param $links
* A flat array of menu links that are part of the menu. Each array element
@@ -1554,7 +1556,7 @@ function menu_tree_data(array $links, array $parents = array(), $depth = 1) {
}
/**
- * Recursive helper function to build the data representing a menu tree.
+ * Builds the data representing a menu tree.
*
* The function is a bit complex because the rendering of a link depends on
* the next menu link.
@@ -1783,7 +1785,7 @@ function menu_get_names() {
}
/**
- * Return an array containing the names of system-defined (default) menus.
+ * Returns an array containing the names of system-defined (default) menus.
*/
function menu_list_system_menus() {
return array(
@@ -1795,14 +1797,14 @@ function menu_list_system_menus() {
}
/**
- * Return an array of links to be rendered as the Main menu.
+ * Returns an array of links to be rendered as the Main menu.
*/
function menu_main_menu() {
return menu_navigation_links(variable_get('menu_main_links_source', 'main-menu'));
}
/**
- * Return an array of links to be rendered as the Secondary links.
+ * Returns an array of links to be rendered as the Secondary links.
*/
function menu_secondary_menu() {
@@ -1817,7 +1819,7 @@ function menu_secondary_menu() {
}
/**
- * Return an array of links for a navigation menu.
+ * Returns an array of links for a navigation menu.
*
* @param $menu_name
* The name of the menu.
@@ -2109,14 +2111,12 @@ function menu_local_tasks($level = 0) {
}
/**
- * Retrieve contextual links for a system object based on registered local tasks.
+ * Retrieves contextual links for a path based on registered local tasks.
*
* This leverages the menu system to retrieve the first layer of registered
* local tasks for a given system path. All local tasks of the tab type
* MENU_CONTEXT_INLINE are taken into account.
*
- * @see hook_menu()
- *
* For example, when considering the following registered local tasks:
* - node/%node/view (default local task) with no 'context' defined
* - node/%node/edit with context: MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE
@@ -2144,6 +2144,7 @@ function menu_local_tasks($level = 0) {
* A list of menu router items that are local tasks for the passed-in path.
*
* @see contextual_links_preprocess()
+ * @see hook_menu()
*/
function menu_contextual_links($module, $parent_path, $args) {
static $path_empty = array();
@@ -2237,7 +2238,7 @@ function menu_local_actions() {
}
/**
- * Returns the router path, or the path of the parent tab of a default local task.
+ * Returns the router path, or the path for a default local task's parent.
*/
function menu_tab_root_path() {
$links = menu_local_tasks();
@@ -2280,7 +2281,9 @@ function theme_menu_local_tasks(&$variables) {
}
/**
- * Set (or get) the active menu for the current page - determines the active trail.
+ * Sets (or gets) the active menu for the current page.
+ *
+ * The active menu for the page determines the active trail.
*
* @return
* An array of menu machine names, in order of preference. The
@@ -2302,17 +2305,17 @@ function menu_set_active_menu_names($menu_names = NULL) {
}
/**
- * Get the active menu for the current page - determines the active trail.
+ * Gets the active menu for the current page.
*/
function menu_get_active_menu_names() {
return menu_set_active_menu_names();
}
/**
- * Set the active path, which determines which page is loaded.
+ * Sets the active path, which determines which page is loaded.
*
* Note that this may not have the desired effect unless invoked very early
- * in the page load, such as during hook_boot, or unless you call
+ * in the page load, such as during hook_boot(), or unless you call
* menu_execute_active_handler() to generate your page output.
*
* @param $path
@@ -2326,7 +2329,7 @@ function menu_set_active_item($path) {
}
/**
- * Sets the active trail (path to menu tree root) of the current page.
+ * Sets the active trail (path to the menu tree root) of the current page.
*
* Any trail set by this function will only be used for functionality that calls
* menu_get_active_trail(). Drupal core only uses trails set here for
@@ -2416,7 +2419,7 @@ function menu_set_active_trail($new_trail = NULL) {
}
/**
- * Lookup the preferred menu link for a given system path.
+ * Looks up the preferred menu link for a given system path.
*
* @param $path
* The path, for example 'node/5'. The function will find the corresponding
@@ -2536,7 +2539,7 @@ function menu_get_active_trail() {
}
/**
- * Get the breadcrumb for the current page, as determined by the active trail.
+ * Gets the breadcrumb for the current page, as determined by the active trail.
*
* @see menu_set_active_trail()
*/
@@ -2587,7 +2590,7 @@ function menu_get_active_breadcrumb() {
}
/**
- * Get the title of the current page, as determined by the active trail.
+ * Gets the title of the current page, as determined by the active trail.
*/
function menu_get_active_title() {
$active_trail = menu_get_active_trail();
@@ -2600,7 +2603,7 @@ function menu_get_active_title() {
}
/**
- * Get a menu link by its mlid, access checked and link translated for rendering.
+ * Gets a translated, access-checked menu link that is ready for rendering.
*
* This function should never be called from within node_load() or any other
* function used as a menu object load function since an infinite recursion may
@@ -2651,7 +2654,9 @@ function menu_cache_clear($menu_name = 'navigation') {
}
/**
- * Clears all cached menu data. This should be called any time broad changes
+ * Clears all cached menu data.
+ *
+ * This should be called any time broad changes
* might have been made to the router items or menu links.
*/
function menu_cache_clear_all() {
@@ -2672,10 +2677,10 @@ function menu_reset_static_cache() {
}
/**
- * (Re)populate the database tables used by various menu functions.
+ * Populates the database tables used by various menu functions.
*
* This function will clear and populate the {menu_router} table, add entries
- * to {menu_links} for new router items, then remove stale items from
+ * to {menu_links} for new router items, and then remove stale items from
* {menu_links}. If called from update.php or install.php, it will also
* schedule a call to itself on the first real page load from
* menu_execute_active_handler(), because the maintenance page environment
@@ -2721,7 +2726,7 @@ function menu_rebuild() {
}
/**
- * Collect and alter the menu definitions.
+ * Collects and alters the menu definitions.
*/
function menu_router_build() {
// We need to manually call each module so that we can know which module
@@ -2745,7 +2750,7 @@ function menu_router_build() {
}
/**
- * Helper function to store the menu router if we have it in memory.
+ * Stores the menu router if we have it in memory.
*/
function _menu_router_cache($new_menu = NULL) {
$menu = &drupal_static(__FUNCTION__);
@@ -2757,7 +2762,7 @@ function _menu_router_cache($new_menu = NULL) {
}
/**
- * Get the menu router.
+ * Gets the menu router.
*/
function menu_get_router() {
// Check first if we have it in memory already.
@@ -2794,7 +2799,7 @@ function _menu_link_build($item) {
}
/**
- * Helper function to build menu links for the items in the menu router.
+ * Builds menu links for the items in the menu router.
*/
function _menu_navigation_links_rebuild($menu) {
// Add normal and suggested items as links.
@@ -2894,7 +2899,7 @@ function _menu_navigation_links_rebuild($menu) {
}
/**
- * Clone an array of menu links.
+ * Clones an array of menu links.
*
* @param $links
* An array of menu links to clone.
@@ -2985,12 +2990,14 @@ function menu_link_delete($mlid, $path = NULL) {
}
/**
- * Helper function for menu_link_delete; deletes a single menu link.
+ * Deletes a single menu link.
*
* @param $item
* Item to be deleted.
* @param $force
* Forces deletion. Internal use only, setting to TRUE is discouraged.
+ *
+ * @see menu_link_delete()
*/
function _menu_delete_item($item, $force = FALSE) {
$item = is_object($item) ? get_object_vars($item) : $item;
@@ -3202,7 +3209,7 @@ function menu_link_save(&$item, $existing_item = array(), $parent_candidates = a
}
/**
- * Find a possible parent for a given menu link.
+ * Finds a possible parent for a given menu link.
*
* Because the parent of a given link might not exist anymore in the database,
* we apply a set of heuristics to determine a proper parent:
@@ -3216,6 +3223,7 @@ function menu_link_save(&$item, $existing_item = array(), $parent_candidates = a
* A menu link.
* @param $parent_candidates
* An array of menu links keyed by mlid.
+ *
* @return
* A menu link structure of the possible parent or FALSE if no valid parent
* has been found.
@@ -3281,7 +3289,7 @@ function _menu_link_find_parent($menu_link, $parent_candidates = array()) {
}
/**
- * Helper function to clear the page and block caches at most twice per page load.
+ * Clears the page and block caches at most twice per page load.
*/
function _menu_clear_page_cache() {
$cache_cleared = &drupal_static(__FUNCTION__, 0);
@@ -3303,7 +3311,7 @@ function _menu_clear_page_cache() {
}
/**
- * Helper function to update a list of menus with expanded items
+ * Updates a list of menus with expanded items.
*/
function _menu_set_expanded_menus() {
$names = db_query("SELECT menu_name FROM {menu_links} WHERE expanded <> 0 GROUP BY menu_name")->fetchCol();
@@ -3311,7 +3319,7 @@ function _menu_set_expanded_menus() {
}
/**
- * Find the router path which will serve this path.
+ * Finds the router path which will serve this path.
*
* @param $link_path
* The path for we are looking up its router path.
@@ -3353,7 +3361,7 @@ function _menu_find_router_path($link_path) {
}
/**
- * Insert, update or delete an uncustomized menu link related to a module.
+ * Inserts, updates, or deletes an uncustomized menu link related to a module.
*
* @param $module
* The name of the module.
@@ -3393,7 +3401,7 @@ function menu_link_maintain($module, $op, $link_path, $link_title) {
}
/**
- * Find the depth of an item's children relative to its depth.
+ * Finds the depth of an item's children relative to its depth.
*
* For example, if the item has a depth of 2, and the maximum of any child in
* the menu link tree is 5, the relative depth is 3.
@@ -3425,7 +3433,7 @@ function menu_link_children_relative_depth($item) {
}
/**
- * Update the children of a menu link that's being moved.
+ * Updates the children of a menu link that is being moved.
*
* The menu name, parents (p1 - p6), and depth are updated for all children of
* the link, and the has_children status of the previous parent is updated.
@@ -3474,7 +3482,7 @@ function _menu_link_move_children($item, $existing_item) {
}
/**
- * Check and update the has_children status for the parent of a link.
+ * Checks and updates the 'has_children' status for the parent of a link.
*/
function _menu_update_parental_status($item, $exclude = FALSE) {
// If plid == 0, there is nothing to update.
@@ -3498,7 +3506,7 @@ function _menu_update_parental_status($item, $exclude = FALSE) {
}
/**
- * Helper function that sets the p1..p9 values for a menu link being saved.
+ * Sets the p1 through p9 values for a menu link being saved.
*/
function _menu_link_parents_set(&$item, $parent) {
$i = 1;
@@ -3516,7 +3524,7 @@ function _menu_link_parents_set(&$item, $parent) {
}
/**
- * Helper function to build the router table based on the data from hook_menu.
+ * Builds the router table based on the data from hook_menu().
*/
function _menu_router_build($callbacks) {
// First pass: separate callbacks from paths, making paths ready for
@@ -3743,7 +3751,7 @@ function _menu_router_build($callbacks) {
}
/**
- * Helper function to save data from menu_router_build() to the router table.
+ * Saves data from menu_router_build() to the router table.
*/
function _menu_router_save($menu, $masks) {
// Delete the existing router since we have some data to replace it.
diff --git a/includes/module.inc b/includes/module.inc
index c07ec63..72c5938 100644
--- a/includes/module.inc
+++ b/includes/module.inc
@@ -6,7 +6,7 @@
*/
/**
- * Load all the modules that have been enabled in the system table.
+ * Loads all the modules that have been enabled in the system table.
*
* @param $bootstrap
* Whether to load only the reduced set of modules loaded in "bootstrap mode"
@@ -102,7 +102,7 @@ function module_list($refresh = FALSE, $bootstrap_refresh = FALSE, $sort = FALSE
}
/**
- * Build a list of bootstrap modules and enabled modules and themes.
+ * Builds a list of bootstrap modules and enabled modules and themes.
*
* @param $type
* The type of list to return:
@@ -219,7 +219,7 @@ function system_list($type) {
}
/**
- * Reset all system_list() caches.
+ * Resets all system_list() caches.
*/
function system_list_reset() {
drupal_static_reset('system_list');
@@ -230,7 +230,7 @@ function system_list_reset() {
}
/**
- * Find dependencies any level deep and fill in required by information too.
+ * Determines which modules require and are required by each module.
*
* @param $files
* The array of filesystem objects used to rebuild the cache.
@@ -263,7 +263,7 @@ function _module_build_dependencies($files) {
}
/**
- * Determine whether a given module exists.
+ * Determines whether a given module exists.
*
* @param $module
* The name of the module (without the .module extension).
@@ -277,7 +277,7 @@ function module_exists($module) {
}
/**
- * Load a module's installation hooks.
+ * Loads a module's installation hooks.
*
* @param $module
* The name of the module (without the .module extension).
@@ -293,7 +293,7 @@ function module_load_install($module) {
}
/**
- * Load a module include file.
+ * Loads a module include file.
*
* Examples:
* @code
@@ -335,8 +335,7 @@ function module_load_include($type, $module, $name = NULL) {
}
/**
- * Load an include file for each of the modules that have been enabled in
- * the system table.
+ * Loads an include file for each module enabled in the {system} table.
*/
function module_load_all_includes($type, $name = NULL) {
$modules = module_list();
@@ -504,7 +503,7 @@ function module_enable($module_list, $enable_dependencies = TRUE) {
}
/**
- * Disable a given set of modules.
+ * Disables a given set of modules.
*
* @param $module_list
* An array of module names.
@@ -615,7 +614,7 @@ function module_disable($module_list, $disable_dependents = TRUE) {
*/
/**
- * Determine whether a module implements a hook.
+ * Determines whether a module implements a hook.
*
* @param $module
* The name of the module (without the .module extension).
@@ -644,7 +643,7 @@ function module_hook($module, $hook) {
}
/**
- * Determine which modules are implementing a hook.
+ * Determines which modules are implementing a hook.
*
* @param $hook
* The name of the hook (e.g. "help" or "menu").
@@ -745,7 +744,7 @@ function module_implements($hook, $sort = FALSE, $reset = FALSE) {
}
/**
- * Retrieve a list of what hooks are explicitly declared.
+ * Retrieves a list of what hooks are explicitly declared.
*/
function module_hook_info() {
// This function is indirectly invoked from bootstrap_invoke_all(), in which
@@ -807,7 +806,7 @@ function module_implements_write_cache() {
}
/**
- * Invoke a hook in a particular module.
+ * Invokes a hook in a particular module.
*
* @param $module
* The name of the module (without the .module extension).
@@ -829,7 +828,7 @@ function module_invoke($module, $hook) {
}
/**
- * Invoke a hook in all enabled modules that implement it.
+ * Invokes a hook in all enabled modules that implement it.
*
* @param $hook
* The name of the hook to invoke.
@@ -866,7 +865,7 @@ function module_invoke_all($hook) {
*/
/**
- * Array of modules required by core.
+ * Returns an array of modules required by core.
*/
function drupal_required_modules() {
$files = drupal_system_listing('/^' . DRUPAL_PHP_FUNCTION_PATTERN . '\.info$/', 'modules', 'name', 0);
@@ -886,7 +885,7 @@ function drupal_required_modules() {
}
/**
- * Hands off alterable variables to type-specific *_alter implementations.
+ * Passes alterable variables to specific hook_TYPE_alter() implementations.
*
* This dispatch function hands off the passed-in variables to type-specific
* hook_TYPE_alter() implementations in modules. It ensures a consistent