From 558c3501480119ca791ee54ae33f701d1fa69033 Mon Sep 17 00:00:00 2001
From: Bram Goffings <bramgoffings@gmail.com>
Date: Mon, 18 Jun 2012 19:07:06 +0200
Subject: [PATCH] shortcut cleanup

---
 core/modules/shortcut/shortcut.admin.inc |   90 +++++++++++++++++++----------
 core/modules/shortcut/shortcut.admin.js  |    6 ++
 core/modules/shortcut/shortcut.api.php   |    1 +
 core/modules/shortcut/shortcut.module    |   44 +++++++++++----
 4 files changed, 99 insertions(+), 42 deletions(-)

diff --git a/core/modules/shortcut/shortcut.admin.inc b/core/modules/shortcut/shortcut.admin.inc
index 9f1888a..559b821 100644
--- a/core/modules/shortcut/shortcut.admin.inc
+++ b/core/modules/shortcut/shortcut.admin.inc
@@ -20,7 +20,7 @@ function shortcut_max_slots() {
 }
 
 /**
- * Form callback: builds the form for switching shortcut sets.
+ * Form constructor for the switch shortcut sets form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -33,9 +33,9 @@ function shortcut_max_slots() {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_set_switch_validate()
  * @see shortcut_set_switch_submit()
+ * @ingroup forms
  */
 function shortcut_set_switch($form, &$form_state, $account = NULL) {
   global $user;
@@ -106,7 +106,9 @@ function shortcut_set_switch($form, &$form_state, $account = NULL) {
 }
 
 /**
- * Validation handler for shortcut_set_switch().
+ * Form validation handler for shortcut_set_switch().
+ *
+ * @see shortcut_set_switch_submit()
  */
 function shortcut_set_switch_validate($form, &$form_state) {
   if ($form_state['values']['set'] == 'new') {
@@ -122,7 +124,9 @@ function shortcut_set_switch_validate($form, &$form_state) {
 }
 
 /**
- * Submit handler for shortcut_set_switch().
+ * Form submission handler for shortcut_set_switch().
+ *
+ * @see shortcut_set_switch_validate()
  */
 function shortcut_set_switch_submit($form, &$form_state) {
   global $user;
@@ -166,7 +170,12 @@ function shortcut_set_switch_submit($form, &$form_state) {
 }
 
 /**
- * Menu page callback: builds the page for administering shortcut sets.
+ * Page callback: Builds the page for administering shortcut sets.
+ *
+ * @return
+ *   An HTML string themed into a table for administering shortcuts.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_admin() {
   $shortcut_sets = shortcut_sets();
@@ -193,7 +202,7 @@ function shortcut_set_admin() {
 }
 
 /**
- * Form callback: builds the form for adding a shortcut set.
+ * Form constructor for the add shortcut set form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -203,9 +212,9 @@ function shortcut_set_admin() {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_set_add_form_validate()
  * @see shortcut_set_add_form_submit()
+ * @ingroup forms
  */
 function shortcut_set_add_form($form, &$form_state) {
   $form['new'] = array(
@@ -225,7 +234,9 @@ function shortcut_set_add_form($form, &$form_state) {
 }
 
 /**
- * Validation handler for shortcut_set_add_form().
+ * Form validation handler for shortcut_set_add_form().
+ *
+ * @see shortcut_set_add_form_submit()
  */
 function shortcut_set_add_form_validate($form, &$form_state) {
   // Check to prevent a duplicate title.
@@ -235,7 +246,9 @@ function shortcut_set_add_form_validate($form, &$form_state) {
 }
 
 /**
- * Submit handler for shortcut_set_add_form().
+ * Form submission handler for shortcut_set_add_form().
+ *
+ * @see shortcut_set_add_form_validate()
  */
 function shortcut_set_add_form_submit($form, &$form_state) {
   // Save a new shortcut set with links copied from the user's default set.
@@ -250,7 +263,7 @@ function shortcut_set_add_form_submit($form, &$form_state) {
 }
 
 /**
- * Form callback: builds the form for customizing shortcut sets.
+ * Form constructor for the customize shortcut sets form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -262,8 +275,8 @@ function shortcut_set_add_form_submit($form, &$form_state) {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_set_customize_submit()
+ * @ingroup forms
  */
 function shortcut_set_customize($form, &$form_state, $shortcut_set) {
   $form['#shortcut_set_name'] = $shortcut_set->set_name;
@@ -315,7 +328,9 @@ function shortcut_set_customize($form, &$form_state, $shortcut_set) {
 }
 
 /**
- * Submit handler for shortcut_set_customize().
+ * Form submission handler for shortcut_set_customize().
+ *
+ * @see shortcut_set_customize()
  */
 function shortcut_set_customize_submit($form, &$form_state) {
   foreach ($form_state['values']['shortcuts'] as $group => $links) {
@@ -402,7 +417,7 @@ function theme_shortcut_set_customize($variables) {
 }
 
 /**
- * Form callback: builds the form for adding a new shortcut link.
+ * Form constructor for the add a new shortcut link form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -414,9 +429,9 @@ function theme_shortcut_set_customize($variables) {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_link_edit_validate()
  * @see shortcut_link_add_submit()
+ * @ingroup forms
  */
 function shortcut_link_add($form, &$form_state, $shortcut_set) {
   drupal_set_title(t('Add new shortcut'));
@@ -429,7 +444,7 @@ function shortcut_link_add($form, &$form_state, $shortcut_set) {
 }
 
 /**
- * Form callback: builds the form for editing a shortcut link.
+ * Form constructor for the edit a shortcut link form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -441,9 +456,9 @@ function shortcut_link_add($form, &$form_state, $shortcut_set) {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_link_edit_validate()
  * @see shortcut_link_edit_submit()
+ * @ingroup forms
  */
 function shortcut_link_edit($form, &$form_state, $shortcut_link) {
   drupal_set_title(t('Editing @shortcut', array('@shortcut' => $shortcut_link['link_title'])));
@@ -456,7 +471,7 @@ function shortcut_link_edit($form, &$form_state, $shortcut_link) {
 }
 
 /**
- * Helper function for building a form for adding or editing shortcut links.
+ * Builds a form for adding or editing shortcut links.
  *
  * @param $shortcut_link
  *   (optional) An array representing the shortcut link that will be edited. If
@@ -507,7 +522,10 @@ function _shortcut_link_form_elements($shortcut_link = NULL) {
 }
 
 /**
- * Validation handler for the shortcut link add and edit forms.
+ * Form validation handler for the shortcut link add and edit forms.
+ *
+ * @see shortcut_link_add_submit()
+ * @see shortcut_link_edit_submit()
  */
 function shortcut_link_edit_validate($form, &$form_state) {
   if (!shortcut_valid_link($form_state['values']['shortcut_link']['link_path'])) {
@@ -516,7 +534,9 @@ function shortcut_link_edit_validate($form, &$form_state) {
 }
 
 /**
- * Submit handler for shortcut_link_edit().
+ * Form submission handler for shortcut_link_edit().
+ *
+ * @see shortcut_link_edit_validate()
  */
 function shortcut_link_edit_submit($form, &$form_state) {
   // Normalize the path in case it is an alias.
@@ -530,7 +550,9 @@ function shortcut_link_edit_submit($form, &$form_state) {
 }
 
 /**
- * Submit handler for shortcut_link_add().
+ * Form submission handler for shortcut_link_add().
+ *
+ * @see shortcut_link_edit_validate()
  */
 function shortcut_link_add_submit($form, &$form_state) {
   // Add the shortcut link to the set.
@@ -584,7 +606,7 @@ function shortcut_admin_add_link($shortcut_link, &$shortcut_set, $limit = NULL)
 }
 
 /**
- * Form callback: builds the form for editing the shortcut set name.
+ * Form constructor for the edit the shortcut set name form.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -597,9 +619,9 @@ function shortcut_admin_add_link($shortcut_link, &$shortcut_set, $limit = NULL)
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_set_edit_form_validate()
  * @see shortcut_set_edit_form_submit()
+ * @ingroup forms
  */
 function shortcut_set_edit_form($form, &$form_state, $shortcut_set) {
   $form['shortcut_set'] = array(
@@ -625,7 +647,9 @@ function shortcut_set_edit_form($form, &$form_state, $shortcut_set) {
 }
 
 /**
- * Validation handler for shortcut_set_edit_form().
+ * Form validation handler for shortcut_set_edit_form().
+ *
+ * @see shortcut_set_edit_form_submit()
  */
 function shortcut_set_edit_form_validate($form, &$form_state) {
   // Check to prevent a duplicate title, if the title was edited from its
@@ -636,7 +660,9 @@ function shortcut_set_edit_form_validate($form, &$form_state) {
 }
 
 /**
- * Submit handler for shortcut_set_edit_form().
+ * Form submission handler for shortcut_set_edit_form().
+ *
+ * @see shortcut_set_edit_form_validate()
  */
 function shortcut_set_edit_form_submit($form, &$form_state) {
   $shortcut_set = $form_state['values']['shortcut_set'];
@@ -647,7 +673,7 @@ function shortcut_set_edit_form_submit($form, &$form_state) {
 }
 
 /**
- * Form callback: builds the confirmation form for deleting a shortcut set.
+ * Form constructor for the confirmation for deleting a shortcut set.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -660,8 +686,8 @@ function shortcut_set_edit_form_submit($form, &$form_state) {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_set_delete_form_submit()
+ * @ingroup forms
  */
 function shortcut_set_delete_form($form, &$form_state, $shortcut_set) {
   $form['shortcut_set'] = array(
@@ -700,7 +726,7 @@ function shortcut_set_delete_form($form, &$form_state, $shortcut_set) {
 }
 
 /**
- * Submit handler for shortcut_set_delete_form().
+ * Form submission handler for shortcut_set_delete_form().
  */
 function shortcut_set_delete_form_submit($form, &$form_state) {
   $shortcut_set = shortcut_set_load($form_state['values']['shortcut_set']);
@@ -710,7 +736,7 @@ function shortcut_set_delete_form_submit($form, &$form_state) {
 }
 
 /**
- * Form callback: builds the confirmation form for deleting a shortcut link.
+ * Form constructor for the confirmation for deleting a shortcut link.
  *
  * @param $form
  *   An associative array containing the structure of the form.
@@ -722,8 +748,8 @@ function shortcut_set_delete_form_submit($form, &$form_state) {
  * @return
  *   An array representing the form definition.
  *
- * @ingroup forms
  * @see shortcut_link_delete_submit()
+ * @ingroup forms
  */
 function shortcut_link_delete($form, &$form_state, $shortcut_link) {
   $form['shortcut_link'] = array(
@@ -742,7 +768,7 @@ function shortcut_link_delete($form, &$form_state, $shortcut_link) {
 }
 
 /**
- * Submit handler for shortcut_link_delete_submit().
+ * Form submission handler for shortcut_link_delete_submit().
  */
 function shortcut_link_delete_submit($form, &$form_state) {
   $shortcut_link = $form_state['values']['shortcut_link'];
@@ -752,12 +778,14 @@ function shortcut_link_delete_submit($form, &$form_state) {
 }
 
 /**
- * Menu page callback: creates a new link in the provided shortcut set.
+ * Page callback: Creates a new link in the provided shortcut set.
  *
  * After completion, redirects the user back to where they came from.
  *
  * @param $shortcut_set
  *   Returned from shortcut_set_load().
+ *
+ * @see shortcut_menu()
  */
 function shortcut_link_add_inline($shortcut_set) {
   if (isset($_REQUEST['token']) && drupal_valid_token($_REQUEST['token'], 'shortcut-add-link') && shortcut_valid_link($_GET['link'])) {
diff --git a/core/modules/shortcut/shortcut.admin.js b/core/modules/shortcut/shortcut.admin.js
index 4530df5..5e5d4fa 100644
--- a/core/modules/shortcut/shortcut.admin.js
+++ b/core/modules/shortcut/shortcut.admin.js
@@ -1,3 +1,9 @@
+
+/**
+ * @file
+ * jQuery behaviors for the Shortcut module.
+ */
+
 (function ($) {
 
 "use strict";
diff --git a/core/modules/shortcut/shortcut.api.php b/core/modules/shortcut/shortcut.api.php
index 717a7c9..0022e0c 100644
--- a/core/modules/shortcut/shortcut.api.php
+++ b/core/modules/shortcut/shortcut.api.php
@@ -26,6 +26,7 @@
  *
  * @param $account
  *   The user account whose default shortcut set is being requested.
+ *
  * @return
  *   The name of the shortcut set that this module recommends for that user, if
  *   there is one.
diff --git a/core/modules/shortcut/shortcut.module b/core/modules/shortcut/shortcut.module
index be29dce..dea9fea 100644
--- a/core/modules/shortcut/shortcut.module
+++ b/core/modules/shortcut/shortcut.module
@@ -207,7 +207,7 @@ function shortcut_block_view($delta = '') {
 }
 
 /**
- * Access callback for editing a shortcut set.
+ * Access callback: Checks permission for editing a shortcut set.
  *
  * @param object $shortcut_set
  *   (optional) The shortcut set to be edited. If not set, the current user's
@@ -216,6 +216,8 @@ function shortcut_block_view($delta = '') {
  * @return
  *   TRUE if the current user has access to edit the shortcut set, FALSE
  *   otherwise.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_edit_access($shortcut_set = NULL) {
   // Sufficiently-privileged users can edit their currently displayed shortcut
@@ -230,14 +232,16 @@ function shortcut_set_edit_access($shortcut_set = NULL) {
 }
 
 /**
- * Access callback for deleting a shortcut set.
+ * Access callback: Checks permission for deleting a shortcut set.
  *
  * @param $shortcut_set
  *   The shortcut set to be deleted.
  *
  * @return
- *   TRUE if the current user has access to delete shortcut sets and this is
- *   not the site-wide default set; FALSE otherwise.
+ *   A boolean value. TRUE if the current user has access to delete shortcut
+ *   sets and this is not the site-wide default set.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_delete_access($shortcut_set) {
   // Only admins can delete sets.
@@ -254,7 +258,7 @@ function shortcut_set_delete_access($shortcut_set) {
 }
 
 /**
- * Access callback for switching the shortcut set assigned to a user account.
+ * Access callback: Checks permission for switching the shortcut set.
  *
  * @param object $account
  *   (optional) The user account whose shortcuts will be switched. If not set,
@@ -264,6 +268,8 @@ function shortcut_set_delete_access($shortcut_set) {
  * @return
  *   TRUE if the current user has access to switch the shortcut set of the
  *   provided account, FALSE otherwise.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_switch_access($account = NULL) {
   global $user;
@@ -288,7 +294,16 @@ function shortcut_set_switch_access($account = NULL) {
 }
 
 /**
- * Access callback for editing a link in a shortcut set.
+ * Access callback: Checks permission for editing a link in a shortcut set.
+ *
+ * @param $menu_link
+ *   The menu link whose access will be checked.
+ *
+ * @return
+ *   A boolean value. TRUE if the current user has access to a shortcut set
+ *   that contains the provided menu link.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_link_access($menu_link) {
   // The link must belong to a shortcut set that the current user has access
@@ -588,7 +603,7 @@ function shortcut_sets() {
 }
 
 /**
- * Check to see if a shortcut set with the given title already exists.
+ * Checks if a shortcut set with the given title already exists.
  *
  * @param $title
  *   Human-readable name of the shortcut set to check.
@@ -605,6 +620,7 @@ function shortcut_set_title_exists($title) {
  *
  * @param $path
  *   The path to the link.
+ *
  * @return
  *   TRUE if the shortcut link is valid, FALSE otherwise. Valid links are ones
  *   that correspond to actual paths on the site.
@@ -627,6 +643,7 @@ function shortcut_valid_link($path) {
  * @param $shortcut_set
  *   (optional) An object representing the set whose links will be displayed.
  *   If not provided, the user's current set will be displayed.
+ *
  * @return
  *   An array of shortcut links, in the format returned by the menu system.
  *
@@ -721,7 +738,9 @@ function shortcut_page_alter(&$page) {
 }
 
 /**
- * Pre-render function for adding shortcuts to the toolbar drawer.
+ * Render API callback: Adds shortcuts to the toolbar drawer.
+ *
+ * This function is assigned as a #pre_render callback in shortcut_page_alter().
  */
 function shortcut_toolbar_pre_render($toolbar) {
   $links = shortcut_renderable_links();
@@ -754,13 +773,16 @@ function shortcut_toolbar_pre_render($toolbar) {
 }
 
 /**
- * Returns the title of a shortcut set.
- *
- * Title callback for the editing pages for shortcut sets.
+ * Title callback: Returns the title of a shortcut set.
  *
  * @param $shortcut_set
  *   An object representing the shortcut set, as returned by
  *   shortcut_set_load().
+ *
+ * @return
+ *   The title of the shortcut set.
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_title($shortcut_set) {
   return $shortcut_set->title;
-- 
1.7.4.msysgit.0