Issue #1319904 by rc_100, xjm, jhodgdon: Clean up API docs for help module.

3 files changed, 33 insertions, 11 deletions

diff --git a/modules/help/help.admin.inc b/modules/help/help.admin.inc
index 3db06ca1a..ec1a18e33 100644
--- a/modules/help/help.admin.inc
+++ b/modules/help/help.admin.inc
@@ -17,6 +17,9 @@ function help_main() {
 
 /**
  * Menu callback; prints a page listing general help for a module.
+ *
+ * @param $name
+ *   A module name to display a help page for.
  */
 function help_page($name) {
   $output = '';
@@ -46,6 +49,12 @@ function help_page($name) {
   return $output;
 }
 
+/**
+ * Provides a formatted list of available help topics.
+ *
+ * @return
+ *   A string containing the formatted list.
+ */
 function help_links_as_list() {
   $empty_arg = drupal_help_arg();
   $module_info = system_rebuild_module_data();
@@ -58,7 +67,7 @@ function help_links_as_list() {
   }
   asort($modules);
 
-  // Output pretty four-column list
+  // Output pretty four-column list.
   $count = count($modules);
   $break = ceil($count / 4);
   $output = '<div class="clearfix"><div class="help-items"><ul>';
diff --git a/modules/help/help.api.php b/modules/help/help.api.php
index ff2f97c6e..f7d9c08b6 100644
--- a/modules/help/help.api.php
+++ b/modules/help/help.api.php
@@ -42,6 +42,7 @@
  *   the current page's help. Note that depending on which module is invoking
  *   hook_help, $arg may contain only empty strings. Regardless, $arg[0] to
  *   $arg[11] will always be set.
+ *
  * @return
  *   A localized string containing the help text.
  */
diff --git a/modules/help/help.test b/modules/help/help.test
index 73b4dedc8..e72aa4a0e 100644
--- a/modules/help/help.test
+++ b/modules/help/help.test
@@ -5,8 +5,18 @@
  * Tests for help.module.
  */
 
+/**
+ * Tests help display and user access for all modules implementing help.
+ */
 class HelpTestCase extends DrupalWebTestCase {
+  /**
+   * The admin user that will be created.
+   */
   protected $big_user;
+
+  /**
+   * The anonymous user that will be created.
+   */
   protected $any_user;
 
   public static function getInfo() {
@@ -17,9 +27,6 @@ class HelpTestCase extends DrupalWebTestCase {
     );
   }
 
-  /**
-   * Enable modules and create users with specific permissions.
-   */
   function setUp() {
     parent::setUp('blog', 'poll');
 
@@ -31,7 +38,7 @@ class HelpTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Login users, create dblog events, and test dblog functionality through the admin and user interfaces.
+   * Logs in users, creates dblog events, and tests dblog functionality.
    */
   function testHelp() {
     // Login the admin user.
@@ -60,9 +67,10 @@ class HelpTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Verify the logged in user has the desired access to the various help nodes and the nodes display help.
+   * Verifies the logged in user has access to the various help nodes.
    *
-   * @param integer $response HTTP response code.
+   * @param integer $response
+   *   An HTTP response code.
    */
   protected function verifyHelp($response = 200) {
     foreach ($this->modules as $module => $name) {
@@ -77,9 +85,10 @@ class HelpTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Get list of enabled modules that implement hook_help().
+   * Gets the list of enabled modules that implement hook_help().
    *
-   * @return array Enabled modules.
+   * @return array
+   *   A list of enabled modules.
    */
   protected function getModuleList() {
     $this->modules = array();
@@ -94,9 +103,12 @@ class HelpTestCase extends DrupalWebTestCase {
 }
 
 /**
- * Tests module without help to verify it is not listed in help page.
+ * Tests a module without help to verify it is not listed in the help page.
  */
 class NoHelpTestCase extends DrupalWebTestCase {
+  /**
+   * The user who will be created.
+   */
   protected $big_user;
 
   public static function getInfo() {
@@ -114,7 +126,7 @@ class NoHelpTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Ensure modules not implementing help do not appear on admin/help.
+   * Ensures modules not implementing help do not appear on admin/help.
    */
   function testMainPageNoHelp() {
     $this->drupalLogin($this->big_user);