From 0c89f4f21e38d44ad141ee15faa872060c2c7f44 Mon, 9 Jan 2012 23:49:33 +0100
From: Bram Goffings <bramgoffings@gmail.com>
Date: Mon, 9 Jan 2012 23:49:23 +0100
Subject: [PATCH] shortcut patch



diff --git a/core/modules/shortcut/shortcut-rtl.css b/core/modules/shortcut/shortcut-rtl.css
index 5dec957..1c094a6 100644
--- a/core/modules/shortcut/shortcut-rtl.css
+++ b/core/modules/shortcut/shortcut-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Right-to-left language styling for the Shortcut module.
+ */
 
 div#toolbar a#edit-shortcuts {
   position: absolute;
diff --git a/core/modules/shortcut/shortcut.admin.css b/core/modules/shortcut/shortcut.admin.css
index 8ca03be..a057572 100644
--- a/core/modules/shortcut/shortcut.admin.css
+++ b/core/modules/shortcut/shortcut.admin.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Styling for the Shortcut module administration pages.
+ */
 
 .shortcut-slot-hidden {
   display: none;
diff --git a/core/modules/shortcut/shortcut.admin.inc b/core/modules/shortcut/shortcut.admin.inc
index 75c12b4..fd864f4 100644
--- a/core/modules/shortcut/shortcut.admin.inc
+++ b/core/modules/shortcut/shortcut.admin.inc
@@ -18,7 +18,7 @@
 }
 
 /**
- * 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.
@@ -31,9 +31,9 @@
  * @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;
@@ -104,7 +104,9 @@
 }
 
 /**
- * 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') {
@@ -120,7 +122,9 @@
 }
 
 /**
- * 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;
@@ -164,7 +168,11 @@
 }
 
 /**
- * Menu page callback: builds the page for administering shortcut sets.
+ * Page callback: Builds the page for administering shortcut sets.
+ *
+ * Path: admin/config/user-interface/shortcut
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_admin() {
   $shortcut_sets = shortcut_sets();
@@ -191,7 +199,7 @@
 }
 
 /**
- * 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.
@@ -201,9 +209,9 @@
  * @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(
@@ -223,7 +231,9 @@
 }
 
 /**
- * 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.
@@ -233,7 +243,9 @@
 }
 
 /**
- * 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.
@@ -248,7 +260,7 @@
 }
 
 /**
- * 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.
@@ -260,8 +272,8 @@
  * @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;
@@ -313,7 +325,9 @@
 }
 
 /**
- * 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) {
@@ -400,7 +414,7 @@
 }
 
 /**
- * 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.
@@ -412,9 +426,9 @@
  * @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'));
@@ -427,7 +441,7 @@
 }
 
 /**
- * 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.
@@ -439,9 +453,9 @@
  * @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'])));
@@ -454,7 +468,7 @@
 }
 
 /**
- * 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
@@ -505,7 +519,10 @@
 }
 
 /**
- * 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'])) {
@@ -514,7 +531,9 @@
 }
 
 /**
- * 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.
@@ -528,7 +547,9 @@
 }
 
 /**
- * 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.
@@ -582,7 +603,7 @@
 }
 
 /**
- * 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.
@@ -595,9 +616,9 @@
  * @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(
@@ -623,7 +644,9 @@
 }
 
 /**
- * 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
@@ -634,7 +657,9 @@
 }
 
 /**
- * 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'];
@@ -645,7 +670,7 @@
 }
 
 /**
- * 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.
@@ -658,8 +683,8 @@
  * @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(
@@ -698,7 +723,7 @@
 }
 
 /**
- * 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']);
@@ -708,7 +733,7 @@
 }
 
 /**
- * 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.
@@ -720,8 +745,8 @@
  * @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(
@@ -740,7 +765,7 @@
 }
 
 /**
- * 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'];
@@ -750,12 +775,16 @@
 }
 
 /**
- * Menu page callback: creates a new link in the provided shortcut set.
+ * Page callback: Creates a new link in the provided shortcut set.
+ *
+ * Path: admin/config/user-interface/shortcut/%shortcut_set/add-link-inline
  *
  * 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 9a730fa..77298c4 100644
--- a/core/modules/shortcut/shortcut.admin.js
+++ b/core/modules/shortcut/shortcut.admin.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * jQuery behaviors for the Shortcut module.
+ */
+
 (function ($) {
 
 /**
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.css b/core/modules/shortcut/shortcut.css
index 3afcb94..7e5a68e 100644
--- a/core/modules/shortcut/shortcut.css
+++ b/core/modules/shortcut/shortcut.css
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Styling for the Shortcut module.
+ */
+
 div#toolbar a#edit-shortcuts {
   float: right;
   padding: 5px 10px 5px 5px;
diff --git a/core/modules/shortcut/shortcut.module b/core/modules/shortcut/shortcut.module
index a60f8d8..0621025 100644
--- a/core/modules/shortcut/shortcut.module
+++ b/core/modules/shortcut/shortcut.module
@@ -207,15 +207,17 @@
 }
 
 /**
- * Access callback for editing a shortcut set.
+ * Access callback: Checks permission for editing a shortcut set.
+ *
+ * Path:
+ *  - admin/config/user-interface/shortcut/%shortcut_set
+ *  - admin/config/user-interface/shortcut/%shortcut_set/edit
  *
  * @param object $shortcut_set
  *   (optional) The shortcut set to be edited. If not set, the current user's
  *   shortcut set will be used.
  *
- * @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,17 @@
 }
 
 /**
- * Access callback for deleting a shortcut set.
+ * Access callback: Checks permission for deleting a shortcut set.
+ *
+ * Path: admin/config/user-interface/shortcut/%shortcut_set/delete
+ *
+ * Returns TRUE if the current user has access to delete shortcut sets and this
+ * is not the site-wide default 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.
+ * @see shortcut_menu()
  */
 function shortcut_set_delete_access($shortcut_set) {
   // Only admins can delete sets.
@@ -254,16 +259,16 @@
 }
 
 /**
- * Access callback for switching the shortcut set assigned to a user account.
+ * Access callback: Checks permission for switching the shortcut set.
+ *
+ * Path: user/%user/shortcuts
  *
  * @param object $account
  *   (optional) The user account whose shortcuts will be switched. If not set,
  *   permissions will be checked for switching the logged-in user's own
  *   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 +293,19 @@
 }
 
 /**
- * Access callback for editing a link in a shortcut set.
+ * Access callback: Checks permission for editing a link in a shortcut set.
+ *
+ * Path:
+ *  - admin/config/user-interface/shortcut/link/%menu_link
+ *  - admin/config/user-interface/shortcut/link/%menu_link/delete
+ *
+ * Returns TRUE if the current user has access to a shortcut set that contains
+ * the provided menu link.
+ *
+ * @param array $menu_link
+ *   The menu link whose access will be checked.
+ *
+ * @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 +605,7 @@
 }
 
 /**
- * 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 +622,7 @@
  *
  * @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 +645,7 @@
  * @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.
  *
@@ -707,7 +726,9 @@
 }
 
 /**
- * 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();
@@ -735,13 +756,15 @@
 }
 
 /**
- * Returns the title of a shortcut set.
+ * Title callback: Returns the title of a shortcut set.
  *
- * Title callback for the editing pages for shortcut sets.
+ * Path: admin/config/user-interface/shortcut/%shortcut_set
  *
  * @param $shortcut_set
  *   An object representing the shortcut set, as returned by
  *   shortcut_set_load().
+ *
+ * @see shortcut_menu()
  */
 function shortcut_set_title($shortcut_set) {
   return $shortcut_set->title;