From d7c940741139e2f78a0735fc3255d8688ba626c3 Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Fri, 5 Oct 2012 11:12:56 -0700
Subject: [PATCH] Issue #1317626 by Albert Volkman: More API docs cleanup for
 includes H-M

---
 core/includes/install.core.inc | 24 +++++++++++++++++++++++-
 core/includes/install.inc      |  6 +++---
 core/includes/mail.inc         |  3 +++
 core/includes/menu.inc         | 10 ++++++++--
 4 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/core/includes/install.core.inc b/core/includes/install.core.inc
index f822918229..dfb41f51d7 100644
--- a/core/includes/install.core.inc
+++ b/core/includes/install.core.inc
@@ -963,6 +963,7 @@ function install_verify_database_settings() {
  *
  * @see install_settings_form_validate()
  * @see install_settings_form_submit()
+ * @ingroup forms
  */
 function install_settings_form($form, &$form_state, &$install_state) {
   global $databases;
@@ -1182,6 +1183,8 @@ function _install_select_profile($profiles) {
  *
  * @param array $install_state
  *   An array of information about the current installation state.
+ *
+ * @ingroup forms
  */
 function install_select_profile_form($form, &$form_state, $install_state) {
   $profiles = array();
@@ -1242,6 +1245,13 @@ function install_select_profile_form($form, &$form_state, $install_state) {
 
 /**
  * Finds all .po files that are useful to the installer.
+ *
+ * @return
+ *   An associative array of file information objects keyed by file URIs as
+ *   returned by file_scan_directory(). English is removed from the array and
+ *   the object is prepared for database insertion.
+ *
+ * @see file_scan_directory()
  */
 function install_find_translations() {
   $files = install_find_translation_files();
@@ -1364,6 +1374,13 @@ function install_select_language(&$install_state) {
 
 /**
  * Form constructor for the language selection form.
+ *
+ * @param $files
+ *   An associative array of file information objects keyed by file URIs as
+ *   returned by file_scan_directory().
+ *
+ * @see file_scan_directory()
+ * @ingroup forms
  */
 function install_select_language_form($form, &$form_state, $files) {
   include_once DRUPAL_ROOT . '/core/includes/standard.inc';
@@ -1574,6 +1591,7 @@ function install_import_translations(&$install_state) {
  *
  * @see install_configure_form_validate()
  * @see install_configure_form_submit()
+ * @ingroup forms
  */
 function install_configure_form($form, &$form_state, &$install_state) {
   drupal_set_title(st('Configure site'));
@@ -1830,11 +1848,15 @@ function install_check_requirements($install_state) {
 }
 
 /**
- * Returns a Form API array definition for site configuration.
+ * Form constructor for a site configuration form.
+ *
+ * @param $install_state
+ *   An array of information about the current installation state.
  *
  * @see install_configure_form()
  * @see install_configure_form_validate()
  * @see install_configure_form_submit()
+ * @ingroup forms
  */
 function _install_configure_form($form, &$form_state, &$install_state) {
   $form['site_information'] = array(
diff --git a/core/includes/install.inc b/core/includes/install.inc
index 25d2dd833d..3c30c89169 100644
--- a/core/includes/install.inc
+++ b/core/includes/install.inc
@@ -297,13 +297,13 @@ function drupal_install_config_directories() {
 }
 
 /**
- * Checks whether a config directory name is defined, and if so, whether it
- * exists and is writable.
+ * Checks whether a config directory exists and is writable.
  *
  * This partially duplicates install_ensure_config_directory(), but is required
  * since the installer would create the config directory too early in the
  * installation process otherwise (e.g., when only visiting install.php when
- * there is a settings.php already, but not actually executing the installation).
+ * there is a settings.php already, but not actually executing the
+ * installation).
  *
  * @param string $type
  *   Type of config directory to return. Drupal core provides 'active' and
diff --git a/core/includes/mail.inc b/core/includes/mail.inc
index e9778d83e1..283045fcf9 100644
--- a/core/includes/mail.inc
+++ b/core/includes/mail.inc
@@ -301,6 +301,9 @@ function drupal_mail_system($module, $key) {
  * @param $indent (optional)
  *   A string to indent the text with. Only '>' characters are repeated on
  *   subsequent wrapped lines. Others are replaced by spaces.
+ *
+ * @return
+ *   The content of the email as a string with formatting applied.
  */
 function drupal_wrap_mail($text, $indent = '') {
   // Convert CRLF into LF.
diff --git a/core/includes/menu.inc b/core/includes/menu.inc
index 36a92c9fef..70113b0e9e 100644
--- a/core/includes/menu.inc
+++ b/core/includes/menu.inc
@@ -554,7 +554,7 @@ function _menu_load_objects(&$item, &$map) {
 }
 
 /**
- * Checks 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
@@ -1568,7 +1568,7 @@ function _menu_tree_data(&$links, $parents, $depth) {
 }
 
 /**
- * Preprocesses the rendered tree for theme_menu_tree().
+ * Implements template_preprocess_HOOK() for theme_menu_tree().
  */
 function template_preprocess_menu_tree(&$variables) {
   $variables['tree'] = $variables['tree']['#children'];
@@ -2229,7 +2229,13 @@ function menu_local_tabs() {
 /**
  * Returns HTML for primary and secondary local tasks.
  *
+ * @param $variables
+ *   An associative array containing:
+ *     - primary: (optional) An array of local tasks (tabs).
+ *     - secondary: (optional) An array of local tasks (tabs).
+ *
  * @ingroup themeable
+ * @see menu_local_tasks()
  */
 function theme_menu_local_tasks(&$variables) {
   $output = '';
-- 
2.24.1