Issue #1332658 by sven.lauer, David_Rothstein, xjm, Albert Volkman: Clean up API docs for dashboard module.

6 files changed, 47 insertions, 28 deletions

diff --git a/modules/dashboard/dashboard-rtl.css b/modules/dashboard/dashboard-rtl.css
index cfccfa031..8d3d0edd0 100644
--- a/modules/dashboard/dashboard-rtl.css
+++ b/modules/dashboard/dashboard-rtl.css
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Right-to-left specific stylesheet for the Dashboard module.
+ */
+
 #dashboard div.dashboard-region {
   float: right;
 }
diff --git a/modules/dashboard/dashboard.api.php b/modules/dashboard/dashboard.api.php
index 00bfde5a3..623dd30ab 100644
--- a/modules/dashboard/dashboard.api.php
+++ b/modules/dashboard/dashboard.api.php
@@ -11,7 +11,7 @@
  */
 
 /**
- * Adds regions to the dashboard.
+ * Add regions to the dashboard.
  *
  * @return
  *   An array whose keys are the names of the dashboard regions and whose
diff --git a/modules/dashboard/dashboard.css b/modules/dashboard/dashboard.css
index db9243c61..83e9ee464 100644
--- a/modules/dashboard/dashboard.css
+++ b/modules/dashboard/dashboard.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Stylesheet for the Dashboard module.
+ */
 
 #dashboard div.dashboard-region {
   float: left;
diff --git a/modules/dashboard/dashboard.js b/modules/dashboard/dashboard.js
index ebecbf65a..83ffc1f28 100644
--- a/modules/dashboard/dashboard.js
+++ b/modules/dashboard/dashboard.js
@@ -1,7 +1,12 @@
+/**
+ * @file
+ * Attaches behaviors for the Dashboard module.
+ */
+
 (function ($) {
 
 /**
- * Implementation of Drupal.behaviors for dashboard.
+ * Implements Drupal.behaviors for the Dashboard module.
  */
 Drupal.behaviors.dashboard = {
     attach: function (context, settings) {
@@ -39,7 +44,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * Enter "customize" mode by displaying disabled blocks.
+   * Enters "customize" mode by displaying disabled blocks.
    */
   enterCustomizeMode: function () {
     $('#dashboard').addClass('customize-mode customize-inactive');
@@ -51,7 +56,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * Exit "customize" mode by simply forcing a page refresh.
+   * Exits "customize" mode by simply forcing a page refresh.
    */
   exitCustomizeMode: function () {
     $('#dashboard').removeClass('customize-mode customize-inactive');
@@ -60,7 +65,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * Helper for enterCustomizeMode; sets up drag-and-drop and close button.
+   * Sets up the drag-and-drop behavior and the 'close' button.
    */
   setupDrawer: function () {
     $('div.customize .canvas-content input').click(Drupal.behaviors.dashboard.exitCustomizeMode);
@@ -84,7 +89,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * While dragging, make the block appear as a disabled block
+   * Makes the block appear as a disabled block while dragging.
    *
    * This function is called on the jQuery UI Sortable "start" event.
    *
@@ -104,8 +109,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * While dragging, adapt block's width to the width of the region it is moved
-   * into.
+   * Adapts block's width to the region it is moved into while dragging.
    *
    * This function is called on the jQuery UI Sortable "over" event.
    *
@@ -127,8 +131,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * While dragging, adapt block's position to stay connected with the position
-   * of the mouse pointer.
+   * Adapts a block's position to stay connected with the mouse pointer.
    *
    * This function is called on the jQuery UI Sortable "sort" event.
    *
@@ -146,7 +149,7 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * Send block order to the server, and expand previously disabled blocks.
+   * Sends block order to the server, and expand previously disabled blocks.
    *
    * This function is called on the jQuery UI Sortable "update" event.
    *
@@ -198,8 +201,10 @@ Drupal.behaviors.dashboard = {
   },
 
   /**
-   * Return the current order of the blocks in each of the sortable regions,
-   * in query string format.
+   * Returns the current order of the blocks in each of the sortable regions.
+   *
+   * @return
+   *   The current order of the blocks, in query string format.
    */
   getOrder: function () {
     var order = [];
diff --git a/modules/dashboard/dashboard.module b/modules/dashboard/dashboard.module
index 08a4cd2b7..478c85a6e 100644
--- a/modules/dashboard/dashboard.module
+++ b/modules/dashboard/dashboard.module
@@ -1,4 +1,8 @@
 <?php
+/**
+ * @file
+ * Provides a dashboard page in the administrative interface.
+ */
 
 /**
  * Implements hook_help().
@@ -263,7 +267,7 @@ function dashboard_forms() {
 }
 
 /**
- * Dashboard page callback.
+ * Page callback: Displays the dashboard.
  *
  * @param $launch_customize
  *   Whether to launch in customization mode right away. TRUE or FALSE.
@@ -298,7 +302,7 @@ function dashboard_admin($launch_customize = FALSE) {
 }
 
 /**
- * Menu page callback: builds the page for administering dashboard blocks.
+ * Page callback: Builds the page for administering dashboard blocks.
  *
  * This page reuses the Block module's administration form but limits editing
  * to blocks that are available to appear on the dashboard.
@@ -454,7 +458,7 @@ function dashboard_is_visible() {
 }
 
 /**
- * Return an array of dashboard region descriptions, keyed by region name.
+ * Returns an array of dashboard region descriptions, keyed by region name.
  */
 function dashboard_region_descriptions() {
   $regions = module_invoke_all('dashboard_regions');
@@ -463,7 +467,7 @@ function dashboard_region_descriptions() {
 }
 
 /**
- * Return an array of dashboard region names.
+ * Returns an array of dashboard region names.
  */
 function dashboard_regions() {
   $regions = &drupal_static(__FUNCTION__);
@@ -485,7 +489,7 @@ function dashboard_dashboard_regions() {
 }
 
 /**
- * Ajax callback to show disabled blocks in the dashboard customization mode.
+ * Ajax callback: Shows disabled blocks in the dashboard customization mode.
  */
 function dashboard_show_disabled() {
   global $theme_key;
@@ -506,7 +510,7 @@ function dashboard_show_disabled() {
 }
 
 /**
- * Ajax callback to display the rendered contents of a specific block.
+ * Ajax callback: Displays the rendered contents of a specific block.
  *
  * @param $module
  *   The block's module name.
@@ -534,7 +538,7 @@ function dashboard_show_block_content($module, $delta) {
 }
 
 /**
- * Set the new weight of each region according to the drag-and-drop order.
+ * Sets the new weight of each region according to the drag-and-drop order.
  */
 function dashboard_update() {
   drupal_theme_initialize();
@@ -631,7 +635,7 @@ function theme_dashboard_region($variables) {
 }
 
 /**
- * Returns HTML for a set of disabled blocks, for display in dashboard customization mode.
+ * Returns HTML for disabled blocks, for use in dashboard customization mode.
  *
  * @param $variables
  *   An associative array containing:
@@ -653,7 +657,7 @@ function theme_dashboard_disabled_blocks($variables) {
 }
 
 /**
- * Returns HTML for a disabled block, for display in dashboard customization mode.
+ * Returns HTML for disabled blocks, for use in dashboard customization mode.
  *
  * @param $variables
  *   An associative array containing:
diff --git a/modules/dashboard/dashboard.test b/modules/dashboard/dashboard.test
index 7cb93f9f1..56bdb132d 100644
--- a/modules/dashboard/dashboard.test
+++ b/modules/dashboard/dashboard.test
@@ -5,6 +5,9 @@
  * Tests for dashboard.module.
  */
 
+/**
+ * Tests the Dashboard module blocks.
+ */
 class DashboardBlocksTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -33,7 +36,7 @@ class DashboardBlocksTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test adding a block to the dashboard and checking access to it.
+   * Tests adding a block to the dashboard and checking access to it.
    */
   function testDashboardAccess() {
     // Add a new custom block to a dashboard region.
@@ -58,7 +61,7 @@ class DashboardBlocksTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that dashboard regions are displayed or hidden properly.
+   * Tests that dashboard regions are displayed or hidden properly.
    */
   function testDashboardRegions() {
     $dashboard_regions = dashboard_region_descriptions();
@@ -80,8 +83,7 @@ class DashboardBlocksTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that the dashboard module can be disabled and enabled again,
-   * retaining its blocks.
+   * Tests that the dashboard module can be re-enabled, retaining its blocks.
    */
   function testDisableEnable() {
     // Add a new custom block to a dashboard region.
@@ -113,8 +115,7 @@ class DashboardBlocksTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that defining a block with ['properties']['administrative'] = TRUE
-   * adds it as an available block for the dashboard.
+   * Tests that administrative blocks are available for the dashboard.
    */
   function testBlockAvailability() {
     // Test "Recent comments", which should be available (defined as