Issue #1355682 by Zgear, chertzog: API docs cleanup for Path module

5 files changed, 78 insertions, 24 deletions

diff --git a/modules/path/path.admin.inc b/modules/path/path.admin.inc
index f10142b56..28b06189b 100644
--- a/modules/path/path.admin.inc
+++ b/modules/path/path.admin.inc
@@ -6,7 +6,7 @@
  */
 
 /**
- * Return a listing of all defined URL aliases.
+ * Returns a listing of all defined URL aliases.
  *
  * When filter key passed, perform a standard search on the given key,
  * and return the list of matching URL aliases.
@@ -87,7 +87,15 @@ function path_admin_overview($keys = NULL) {
 }
 
 /**
- * Menu callback; handles pages for creating and editing URL aliases.
+ * Page callback: Returns a form creating or editing a path alias.
+ *
+ * @param $path
+ *   An array containing the path ID, source, alias, and language code.
+ *
+ * @return
+ *   A form for adding or editing a URL alias.
+ *
+ * @see path_menu()
  */
 function path_admin_edit($path = array()) {
   if ($path) {
@@ -102,11 +110,15 @@ function path_admin_edit($path = array()) {
 }
 
 /**
- * Return a form for editing or creating an individual URL alias.
+ * Form constructor for the path administration form.
+ *
+ * @param $path
+ *   An array containing the path ID, source, alias, and language code.
  *
  * @ingroup forms
  * @see path_admin_form_validate()
  * @see path_admin_form_submit()
+ * @see path_admin_form_delete_submit()
  */
 function path_admin_form($form, &$form_state, $path = array('source' => '', 'alias' => '', 'language' => LANGUAGE_NONE, 'pid' => NULL)) {
   $form['source'] = array(
@@ -157,7 +169,10 @@ function path_admin_form($form, &$form_state, $path = array('source' => '', 'ali
 }
 
 /**
- * Submit function for the 'Delete' button on the URL alias editing form.
+ * Form submission handler for the 'Delete' button on path_admin_form().
+ *
+ * @see path_admin_form_validate()
+ * @see path_admin_form_submit()
  */
 function path_admin_form_delete_submit($form, &$form_state) {
   $destination = array();
@@ -169,7 +184,10 @@ function path_admin_form_delete_submit($form, &$form_state) {
 }
 
 /**
- * Verify that a URL alias is valid
+ * Form validation handler for path_admin_form().
+ *
+ * @see path_admin_form_submit()
+ * @see path_admin_form_delete_submit()
  */
 function path_admin_form_validate($form, &$form_state) {
   $source = &$form_state['values']['source'];
@@ -195,7 +213,10 @@ function path_admin_form_validate($form, &$form_state) {
 }
 
 /**
- * Save a URL alias to the database.
+ * Form submission handler for path_admin_form().
+ *
+ * @see path_admin_form_validate()
+ * @see path_admin_form_delete_submit()
  */
 function path_admin_form_submit($form, &$form_state) {
   // Remove unnecessary values.
@@ -208,7 +229,12 @@ function path_admin_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; confirms deleting an URL alias
+ * Form constructor for the path deletion form.
+ *
+ * @param $path
+ *   The path alias that will be deleted.
+ *
+ * @see path_admin_delete_confirm_submit()
  */
 function path_admin_delete_confirm($form, &$form_state, $path) {
   if (user_access('administer url aliases')) {
@@ -224,7 +250,7 @@ function path_admin_delete_confirm($form, &$form_state, $path) {
 }
 
 /**
- * Execute URL alias deletion
+ * Form submission handler for path_admin_delete_confirm().
  */
 function path_admin_delete_confirm_submit($form, &$form_state) {
   if ($form_state['values']['confirm']) {
@@ -234,10 +260,11 @@ function path_admin_delete_confirm_submit($form, &$form_state) {
 }
 
 /**
- * Return a form to filter URL aliases.
+ * Form constructor for the path admin overview filter form.
  *
  * @ingroup forms
- * @see path_admin_filter_form_submit()
+ * @see path_admin_filter_form_submit_filter()
+ * @see path_admin_filter_form_submit_reset()
  */
 function path_admin_filter_form($form, &$form_state, $keys = '') {
   $form['#attributes'] = array('class' => array('search-form'));
@@ -269,14 +296,18 @@ function path_admin_filter_form($form, &$form_state, $keys = '') {
 }
 
 /**
- * Process filter form submission when the Filter button is pressed.
+ * Form submission handler for the path_admin_filter_form() Filter button.
+ *
+ * @see path_admin_filter_form_submit_reset()
  */
 function path_admin_filter_form_submit_filter($form, &$form_state) {
   $form_state['redirect'] = 'admin/config/search/path/list/' . trim($form_state['values']['filter']);
 }
 
 /**
- * Process filter form submission when the Reset button is pressed.
+ * Form submission handler for the path_admin_filter_form() Reset button.
+ *
+ * @see path_admin_filter_form_submit_filter()
  */
 function path_admin_filter_form_submit_reset($form, &$form_state) {
   $form_state['redirect'] = 'admin/config/search/path/list';
diff --git a/modules/path/path.api.php b/modules/path/path.api.php
index d1a007ac8..0a17e2c67 100644
--- a/modules/path/path.api.php
+++ b/modules/path/path.api.php
@@ -10,9 +10,8 @@
  * @{
  */
 
-
 /**
- * Allow modules to respond to a path being inserted.
+ * Respond to a path being inserted.
  *
  * @param $path
  *   An associative array containing the following keys:
@@ -33,7 +32,7 @@ function hook_path_insert($path) {
 }
 
 /**
- * Allow modules to respond to a path being updated.
+ * Respond to a path being updated.
  *
  * @param $path
  *   An associative array containing the following keys:
@@ -52,7 +51,7 @@ function hook_path_update($path) {
 }
 
 /**
- * Allow modules to respond to a path being deleted.
+ * Respond to a path being deleted.
  *
  * @param $path
  *   An associative array containing the following keys:
diff --git a/modules/path/path.js b/modules/path/path.js
index fcc0acc41..c4f3cd001 100644
--- a/modules/path/path.js
+++ b/modules/path/path.js
@@ -1,4 +1,9 @@
 
+/**
+ * @file
+ * Attaches behaviors for the Path module.
+ */
+
 (function ($) {
 
 Drupal.behaviors.pathFieldsetSummaries = {
diff --git a/modules/path/path.module b/modules/path/path.module
index 71dd22fa7..9df498865 100644
--- a/modules/path/path.module
+++ b/modules/path/path.module
@@ -91,7 +91,9 @@ function path_menu() {
 }
 
 /**
- * Implements hook_form_BASE_FORM_ID_alter().
+ * Implements hook_form_BASE_FORM_ID_alter() for node_form().
+ *
+ * @see path_form_element_validate()
  */
 function path_form_node_form_alter(&$form, $form_state) {
   $path = array();
@@ -145,6 +147,8 @@ function path_form_node_form_alter(&$form, $form_state) {
 
 /**
  * Form element validation handler for URL alias form element.
+ *
+ * @see path_form_node_form_alter()
  */
 function path_form_element_validate($element, &$form_state, $complete_form) {
   // Trim the submitted value.
@@ -225,7 +229,7 @@ function path_node_delete($node) {
 }
 
 /**
- * Implements hook_form_FORM_ID_alter().
+ * Implements hook_form_FORM_ID_alter() for taxonomy_form_term().
  */
 function path_form_taxonomy_form_term_alter(&$form, $form_state) {
   // Make sure this does not show up on the delete confirmation form.
diff --git a/modules/path/path.test b/modules/path/path.test
index acd4e20a6..f5c303c3a 100644
--- a/modules/path/path.test
+++ b/modules/path/path.test
@@ -2,9 +2,12 @@
 
 /**
  * @file
- * Tests for path.module.
+ * Tests for the Path module.
  */
 
+/**
+ * Provides a base class for testing the Path module.
+ */
 class PathTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -23,7 +26,7 @@ class PathTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test the path cache.
+   * Tests the path cache.
    */
   function testPathCache() {
     // Create test node.
@@ -48,7 +51,7 @@ class PathTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test alias functionality through the admin interfaces.
+   * Tests alias functionality through the admin interfaces.
    */
   function testAdminAlias() {
     // Create test node.
@@ -107,7 +110,7 @@ class PathTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test alias functionality through the node interfaces.
+   * Tests alias functionality through the node interfaces.
    */
   function testNodeAlias() {
     // Create test node.
@@ -159,6 +162,15 @@ class PathTestCase extends DrupalWebTestCase {
     $this->assertResponse(404);
   }
 
+  /**
+   * Returns the path ID.
+   *
+   * @param $alias
+   *   A string containing an aliased path.
+   *
+   * @return int
+   *   Integer representing the path ID.
+   */
   function getPID($alias) {
     return db_query("SELECT pid FROM {url_alias} WHERE alias = :alias", array(':alias' => $alias))->fetchField();
   }
@@ -182,7 +194,7 @@ class PathTestCase extends DrupalWebTestCase {
 }
 
 /**
- * Test URL aliases for taxonomy terms.
+ * Tests URL aliases for taxonomy terms.
  */
 class PathTaxonomyTermTestCase extends DrupalWebTestCase {
   public static function getInfo() {
@@ -202,7 +214,7 @@ class PathTaxonomyTermTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test alias functionality through the admin interfaces.
+   * Tests alias functionality through the admin interfaces.
    */
   function testTermAlias() {
     // Create a term in the default 'Tags' vocabulary with URL alias.
@@ -245,6 +257,9 @@ class PathTaxonomyTermTestCase extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests URL aliases for translated nodes.
+ */
 class PathLanguageTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(