Issue #1332636 by sven.lauer, xjm: Clean up API docs for contact module.

4 files changed, 97 insertions, 46 deletions

diff --git a/modules/contact/contact.admin.inc b/modules/contact/contact.admin.inc
index 9fde037d3..4648fd3d7 100644
--- a/modules/contact/contact.admin.inc
+++ b/modules/contact/contact.admin.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Admin page callbacks for the contact module.
+ * Admin page callbacks for the Contact module.
  */
 
 /**
@@ -53,7 +53,22 @@ function contact_category_list() {
 }
 
 /**
- * Category edit page.
+ * Form constructor for the category edit form.
+ *
+ * @param $category
+ *   An array describing the category to be edited. May be empty for new
+ *   categories. Recognized array keys are:
+ *   - category: The name of the category.
+ *   - recipients: A comma-separated list of recipients.
+ *   - reply: (optional) The body of the auto-reply message.
+ *   - weight: The weight of the category.
+ *   - selected: Boolean indicating whether the category should be selected by
+ *     default.
+ *   - cid: The category ID for which the form is to be displayed.
+ *
+ * @see contact_category_edit_form_validate()
+ * @see contact_category_edit_form_submit()
+ * @ingroup forms
  */
 function contact_category_edit_form($form, &$form_state, array $category = array()) {
   // If this is a new category, add the default values.
@@ -117,7 +132,9 @@ function contact_category_edit_form($form, &$form_state, array $category = array
 }
 
 /**
- * Validate the contact category edit page form submission.
+ * Form validation handler for contact_category_edit_form().
+ *
+ * @see contact_category_edit_form_submit()
  */
 function contact_category_edit_form_validate($form, &$form_state) {
   // Validate and each e-mail recipient.
@@ -144,7 +161,9 @@ function contact_category_edit_form_validate($form, &$form_state) {
 }
 
 /**
- * Process the contact category edit page form submission.
+ * Form submission handler for contact_category_edit_form().
+ *
+ * @see contact_category_edit_form_validate()
  */
 function contact_category_edit_form_submit($form, &$form_state) {
   if ($form_state['values']['selected']) {
@@ -167,8 +186,13 @@ function contact_category_edit_form_submit($form, &$form_state) {
 }
 
 /**
- * Form builder for deleting a contact category.
+ * Form constructor for the contact category deletion form.
+ *
+ * @param $contact
+ *   Array describing the contact category to be deleted. See the documentation
+ *   of contact_category_edit_form() for the recognized keys.
  *
+ * @see contact_menu()
  * @see contact_category_delete_form_submit()
  */
 function contact_category_delete_form($form, &$form_state, array $contact) {
@@ -188,9 +212,7 @@ function contact_category_delete_form($form, &$form_state, array $contact) {
 }
 
 /**
- * Submit handler for the confirm delete category form.
- *
- * @see contact_category_delete_form()
+ * Form submission handler for contact_category_delete_form().
  */
 function contact_category_delete_form_submit($form, &$form_state) {
   $contact = $form['contact']['#value'];
diff --git a/modules/contact/contact.module b/modules/contact/contact.module
index eaae9c62c..a8701827d 100644
--- a/modules/contact/contact.module
+++ b/modules/contact/contact.module
@@ -110,10 +110,7 @@ function contact_menu() {
  * Menu access callback for a user's personal contact form.
  *
  * @param $account
- *   A user account object.
- * @return
- *   TRUE if the current user has access to the requested user's contact form,
- *   or FALSE otherwise.
+ *   The user object of the user whose contact form is being requested.
  */
 function _contact_personal_tab_access($account) {
   global $user;
@@ -148,10 +145,11 @@ function _contact_personal_tab_access($account) {
 }
 
 /**
- * Load a contact category.
+ * Loads a contact category.
  *
  * @param $cid
  *   The contact category ID.
+ *
  * @return
  *   An array with the contact category's data.
  */
@@ -211,6 +209,8 @@ function contact_mail($key, &$message, $params) {
  * Implements hook_form_FORM_ID_alter().
  *
  * Add the enable personal contact form to an individual user's account page.
+ *
+ * @see user_profile_form()
  */
 function contact_form_user_profile_form_alter(&$form, &$form_state) {
   if ($form['#user_category'] == 'account') {
@@ -241,6 +241,8 @@ function contact_user_presave(&$edit, $account, $category) {
  * Implements hook_form_FORM_ID_alter().
  *
  * Add the default personal contact setting on the user settings page.
+ *
+ * @see user_admin_settings()
  */
 function contact_form_user_admin_settings_alter(&$form, &$form_state) {
   $form['contact'] = array(
diff --git a/modules/contact/contact.pages.inc b/modules/contact/contact.pages.inc
index 30b282504..ba8918bf5 100644
--- a/modules/contact/contact.pages.inc
+++ b/modules/contact/contact.pages.inc
@@ -2,14 +2,15 @@
 
 /**
  * @file
- * User page callbacks for the contact module.
+ * Page callbacks for the Contact module.
  */
 
 /**
- * Form builder; the site-wide contact form.
+ * Form constructor for the site-wide contact form.
  *
  * @see contact_site_form_validate()
  * @see contact_site_form_submit()
+ * @ingroup forms
  */
 function contact_site_form($form, &$form_state) {
   global $user;
@@ -112,6 +113,8 @@ function contact_site_form($form, &$form_state) {
 
 /**
  * Form validation handler for contact_site_form().
+ *
+ * @see contact_site_form_submit()
  */
 function contact_site_form_validate($form, &$form_state) {
   if (!$form_state['values']['cid']) {
@@ -124,6 +127,8 @@ function contact_site_form_validate($form, &$form_state) {
 
 /**
  * Form submission handler for contact_site_form().
+ *
+ * @see contact_site_form_validate()
  */
 function contact_site_form_submit($form, &$form_state) {
   global $user, $language;
@@ -166,10 +171,14 @@ function contact_site_form_submit($form, &$form_state) {
 }
 
 /**
- * Form builder; the personal contact form.
+ * Form constructor for the personal contact form.
  *
+ * Path: user/%user/contact
+ *
+ * @see contact_menu()
  * @see contact_personal_form_validate()
  * @see contact_personal_form_submit()
+ * @ingroup forms
  */
 function contact_personal_form($form, &$form_state, $recipient) {
   global $user;
@@ -244,7 +253,7 @@ function contact_personal_form($form, &$form_state, $recipient) {
 /**
  * Form validation handler for contact_personal_form().
  *
- * @see contact_personal_form()
+ * @see contact_personal_form_submit()
  */
 function contact_personal_form_validate($form, &$form_state) {
   if (!valid_email_address($form_state['values']['mail'])) {
@@ -255,7 +264,7 @@ function contact_personal_form_validate($form, &$form_state) {
 /**
  * Form submission handler for contact_personal_form().
  *
- * @see contact_personal_form()
+ * @see contact_personal_form_validate()
  */
 function contact_personal_form_submit($form, &$form_state) {
   global $user, $language;
diff --git a/modules/contact/contact.test b/modules/contact/contact.test
index 129eb30ce..48c8bb01f 100644
--- a/modules/contact/contact.test
+++ b/modules/contact/contact.test
@@ -1,10 +1,12 @@
 <?php
-
 /**
- * @file 
- * Tests for contact.module.
+ * @file
+ * Tests for the Contact module.
  */
 
+/**
+ * Tests the site-wide contact form.
+ */
 class ContactSitewideTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -19,7 +21,7 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test configuration options and site-wide contact form.
+   * Tests configuration options and the site-wide contact form.
    */
   function testSiteWideContact() {
     // Create and login administrative user.
@@ -159,7 +161,7 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-  * Test auto-reply on the site-wide contact form.
+  * Tests auto-reply on the site-wide contact form.
   */
   function testAutoReply() {
     // Create and login administrative user.
@@ -200,12 +202,17 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Add a category.
+   * Adds a category.
    *
-   * @param string $category Name of category.
-   * @param string $recipients List of recipient e-mail addresses.
-   * @param string $reply Auto-reply text.
-   * @param boolean $selected Defautly selected.
+   * @param string $category
+   *   The category name.
+   * @param string $recipients
+   *   The list of recipient e-mail addresses.
+   * @param string $reply
+   *   The auto-reply text that is sent to a user upon completing the contact
+   *   form.
+   * @param boolean $selected
+   *   Boolean indicating whether the category should be selected by default.
    */
   function addCategory($category, $recipients, $reply, $selected) {
     $edit = array();
@@ -217,12 +224,17 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Update a category.
+   * Updates a category.
    *
-   * @param string $category Name of category.
-   * @param string $recipients List of recipient e-mail addresses.
-   * @param string $reply Auto-reply text.
-   * @param boolean $selected Defautly selected.
+   * @param string $category
+   *   The category name.
+   * @param string $recipients
+   *   The list of recipient e-mail addresses.
+   * @param string $reply
+   *   The auto-reply text that is sent to a user upon completing the contact
+   *   form.
+   * @param boolean $selected
+   *   Boolean indicating whether the category should be selected by default.
    */
   function updateCategory($categories, $category, $recipients, $reply, $selected) {
     $category_id = $categories[array_rand($categories)];
@@ -236,13 +248,18 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Submit contact form.
+   * Submits the contact form.
    *
-   * @param string $name Name.
-   * @param string $mail E-mail address.
-   * @param string $subject Subject.
-   * @param integer $cid Category id.
-   * @param string $message Message.
+   * @param string $name
+   *   The name of the sender.
+   * @param string $mail
+   *   The e-mail address of the sender.
+   * @param string $subject
+   *   The subject of the message.
+   * @param integer $cid
+   *   The category ID of the message.
+   * @param string $message
+   *   The message body.
    */
   function submitContact($name, $mail, $subject, $cid, $message) {
     $edit = array();
@@ -255,7 +272,7 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Delete all categories.
+   * Deletes all categories.
    */
   function deleteCategories() {
     $categories = $this->getCategories();
@@ -267,9 +284,10 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Get list category ids.
+   * Gets a list of all category IDs.
    *
-   * @return array Category ids.
+   * @return array
+   *   A list of the category IDs.
    */
   function getCategories() {
     $categories = db_query('SELECT cid FROM {contact}')->fetchCol();
@@ -278,7 +296,7 @@ class ContactSitewideTestCase extends DrupalWebTestCase {
 }
 
 /**
- * Test the personal contact form.
+ * Tests the personal contact form.
  */
 class ContactPersonalTestCase extends DrupalWebTestCase {
   private $admin_user;
@@ -306,7 +324,7 @@ class ContactPersonalTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test personal contact form access.
+   * Tests access to the personal contact form.
    */
   function testPersonalContactAccess() {
     // Test allowed access to user with contact form enabled.
@@ -369,7 +387,7 @@ class ContactPersonalTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test the personal contact form flood protection.
+   * Tests the personal contact form flood protection.
    */
   function testPersonalContactFlood() {
     $flood_limit = 3;
@@ -399,7 +417,7 @@ class ContactPersonalTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Fill out a user's personal contact form and submit.
+   * Fills out a user's personal contact form and submits it.
    *
    * @param $account
    *   A user object of the user being contacted.