From 3375279f209ed447355a250989441f338dc40348 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.css     |    2 +-
 core/modules/shortcut/shortcut.admin.inc     |  175 +++++++++-----------------
 core/modules/shortcut/shortcut.admin.js      |    6 +
 core/modules/shortcut/shortcut.api.php       |    1 +
 core/modules/shortcut/shortcut.base-rtl.css  |    2 +-
 core/modules/shortcut/shortcut.base.css      |    2 +-
 core/modules/shortcut/shortcut.module        |   44 +++++--
 core/modules/shortcut/shortcut.theme-rtl.css |    2 +-
 core/modules/shortcut/shortcut.theme.css     |    2 +-
 9 files changed, 106 insertions(+), 130 deletions(-)

diff --git a/core/modules/shortcut/shortcut.admin.css b/core/modules/shortcut/shortcut.admin.css
index 17d3bab..4b55692 100644
--- a/core/modules/shortcut/shortcut.admin.css
+++ b/core/modules/shortcut/shortcut.admin.css
@@ -1,7 +1,7 @@
 
 /**
  * @file
- * Admin styling for shortcut module.
+ * Admin styling for the Shortcut module.
  */
 
 .shortcut-slot-hidden {
diff --git a/core/modules/shortcut/shortcut.admin.inc b/core/modules/shortcut/shortcut.admin.inc
index 9f1888a..9cda283 100644
--- a/core/modules/shortcut/shortcut.admin.inc
+++ b/core/modules/shortcut/shortcut.admin.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Administrative page callbacks for the shortcut module.
+ * Administrative page callbacks for the Shortcut module.
  */
 
 use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
@@ -20,22 +20,11 @@ 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.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param $account
- *   (optional) The user account whose shortcuts will be switched. Defaults to
- *   the current logged-in user.
- *
- * @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 +95,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 +113,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 +159,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,19 +191,11 @@ 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.
- * @param $form_state
- *   An associative array containing the current state of the form.
- *
- * @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 +215,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 +227,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,20 +244,10 @@ function shortcut_set_add_form_submit($form, &$form_state) {
 }
 
 /**
- * Form callback: builds the form for customizing shortcut sets.
- *
- * @param $form
- *   An associative array containing the structure of the form.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param $shortcut_set
- *   An object representing the shortcut set which is being edited.
+ * Form constructor for the customize shortcut sets form.
  *
- * @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 +299,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,21 +388,11 @@ function theme_shortcut_set_customize($variables) {
 }
 
 /**
- * Form callback: builds the form for adding a new shortcut link.
- *
- * @param $form
- *   An associative array containing the structure of the form.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param $shortcut_set
- *   An object representing the shortcut set to which the link will be added.
+ * Form constructor for the add a new shortcut link form.
  *
- * @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,21 +405,11 @@ 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.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param $shortcut_link
- *   An array representing the link that is being edited.
- *
- * @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 +422,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 +473,10 @@ function _shortcut_link_form_elements($shortcut_link = NULL) {
 }
 
 /**
- * Validation handler for the shortcut link add and edit forms.
+ * Form validation handler for shortcut_link_add() and shortcut_link_edit().
+ *
+ * @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 +485,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 +501,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,22 +557,11 @@ 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.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param object $shortcut_set
- *   An object representing the shortcut set, as returned from
- *   shortcut_set_load().
- *
- * @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 +587,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 +600,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,21 +613,10 @@ 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.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param object $shortcut_set
- *   An object representing the shortcut set, as returned from
- *   shortcut_set_load().
- *
- * @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 +655,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,20 +665,10 @@ function shortcut_set_delete_form_submit($form, &$form_state) {
 }
 
 /**
- * Form callback: builds the confirmation form for deleting a shortcut link.
- *
- * @param $form
- *   An associative array containing the structure of the form.
- * @param $form_state
- *   An associative array containing the current state of the form.
- * @param $shortcut_link
- *   An array representing the link that will be deleted.
- *
- * @return
- *   An array representing the form definition.
+ * Form constructor for the confirmation for deleting a shortcut link.
  *
- * @ingroup forms
  * @see shortcut_link_delete_submit()
+ * @ingroup forms
  */
 function shortcut_link_delete($form, &$form_state, $shortcut_link) {
   $form['shortcut_link'] = array(
@@ -742,7 +687,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 +697,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().
+ *   An object representing the shortcut set which the link will be added to..
+ *
+ * @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.base-rtl.css b/core/modules/shortcut/shortcut.base-rtl.css
index c236f47..739d01c 100644
--- a/core/modules/shortcut/shortcut.base-rtl.css
+++ b/core/modules/shortcut/shortcut.base-rtl.css
@@ -1,7 +1,7 @@
 
 /**
  * @file
- * Generic RTL base styles for shortcut module.
+ * Generic RTL base styles for the Shortcut module.
  */
 
 /**
diff --git a/core/modules/shortcut/shortcut.base.css b/core/modules/shortcut/shortcut.base.css
index 90a1046..30cd1b7 100644
--- a/core/modules/shortcut/shortcut.base.css
+++ b/core/modules/shortcut/shortcut.base.css
@@ -1,7 +1,7 @@
 
 /**
  * @file
- * Generic base styles for shortcut module.
+ * Generic base styles for the Shortcut module.
  */
 
 /**
diff --git a/core/modules/shortcut/shortcut.module b/core/modules/shortcut/shortcut.module
index be29dce..d0d239c 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 whether 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;
diff --git a/core/modules/shortcut/shortcut.theme-rtl.css b/core/modules/shortcut/shortcut.theme-rtl.css
index 981466f..501a1db 100644
--- a/core/modules/shortcut/shortcut.theme-rtl.css
+++ b/core/modules/shortcut/shortcut.theme-rtl.css
@@ -1,7 +1,7 @@
 
 /**
  * @file
- * RTL styling for the shortcut module.
+ * RTL styling for the the Shortcut module.
  */
 
 /**
diff --git a/core/modules/shortcut/shortcut.theme.css b/core/modules/shortcut/shortcut.theme.css
index eff3e93..1a6315f 100644
--- a/core/modules/shortcut/shortcut.theme.css
+++ b/core/modules/shortcut/shortcut.theme.css
@@ -1,7 +1,7 @@
 
 /**
  * @file
- * Styling for the shortcut module.
+ * Styling for the Shortcut module.
  */
 
 /**
-- 
1.7.4.msysgit.0