Issue #1811628 by Lars Toomre: More API docs cleanup for Contact module

core/modules/contact/contact.admin.inc

@@ -10,6 +10,9 @@
 /**
  * Page callback: Lists contact categories.
  *
+ * @return array
+ *   A build array in the format expected by drupal_render().
+ *
  * @see contact_menu()
  */
 function contact_category_list() {
@@ -17,7 +20,12 @@ function contact_category_list() {
 }
 
 /**
- * Page callback: provides the category creation form.
+ * Page callback: Form constructor for the category creation form.
+ *
+ * @return string
+ *   A processed form for the contact category.
+ *
+ * @see contact_menu()
  */
 function contact_category_add() {
   $category = entity_create('contact_category', array());
@@ -25,13 +33,15 @@ function contact_category_add() {
 }
 
 /**
- * Form constructor for the contact category deletion form.
+ * Page callback: Form constructor for the contact category deletion form.
  *
  * @param Drupal\contact\Category $category
  *   The contact category to be deleted.
  *
  * @see contact_menu()
  * @see contact_category_delete_form_submit()
+ *
+ * @ingroup forms
  */
 function contact_category_delete_form($form, &$form_state, Category $category) {
   $form_state['contact_category'] = $category;

core/modules/contact/contact.module

@@ -112,6 +112,10 @@ function contact_menu() {
  * @param $account
  *   The user object of the user whose contact form is being requested.
  *
+ * @return
+ *   A Boolean TRUE if the user has permission to access a personal contact
+ *   form.
+ *
  * @see contact_menu()
  */
 function _contact_personal_tab_access($account) {

core/modules/contact/contact.pages.inc

@@ -9,7 +9,10 @@
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
 /**
- * Form constructor for the site-wide contact form.
+ * Page callback: Form constructor for the site-wide contact form.
+ *
+ * @throws \Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
+ * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
  *
  * @see contact_menu()
  * @see contact_site_form_submit()
@@ -129,8 +132,6 @@ function contact_site_form($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;
@@ -175,10 +176,14 @@ function contact_site_form_submit($form, &$form_state) {
 }
 
 /**
- * Form constructor for the personal contact form.
+ * Page callback: Form constructor for the personal contact form.
+ *
+ * @param $recipient
+ *   The account for which a personal contact form should be generated.
+ *
+ * @throws \Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
  *
  * @see contact_menu()
- * @see contact_personal_form_validate()
  * @see contact_personal_form_submit()
  * @ingroup forms
  */
@@ -270,8 +275,6 @@ function contact_personal_form($form, &$form_state, $recipient) {
 
 /**
  * Form submission handler for contact_personal_form().
- *
- * @see contact_personal_form_validate()
  */
 function contact_personal_form_submit($form, &$form_state) {
   global $user;

core/modules/contact/lib/Drupal/contact/Tests/ContactPersonalTest.php

@@ -21,8 +21,25 @@ class ContactPersonalTest extends WebTestBase {
    */
   public static $modules = array('contact');
 
+  /**
+   * A user with some administrative permissions.
+   *
+   * @var object
+   */
   private $admin_user;
+
+  /**
+   * A user with 'access user contact forms' permission.
+   *
+   * @var object
+   */
   private $web_user;
+
+  /**
+   * A user without any permissions.
+   *
+   * @var object
+   */
   private $contact_user;
 
   public static function getInfo() {
@@ -162,7 +179,8 @@ function testPersonalContactFlood() {
    * @param $account
    *   A user object of the user being contacted.
    * @param $message
-   *   An optional array with the form fields being used.
+   *   (optional) An array with the form fields being used. Defaults to an empty
+   *   array.
    */
   protected function submitPersonalContact($account, array $message = array()) {
     $message += array(

core/modules/contact/lib/Drupal/contact/Tests/ContactSitewideTest.php

@@ -232,7 +232,7 @@ function testAutoReply() {
    *   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.
+   *   A Boolean indicating whether the category should be selected by default.
    */
   function addCategory($id, $label, $recipients, $reply, $selected) {
     $edit = array();
@@ -257,7 +257,7 @@ function addCategory($id, $label, $recipients, $reply, $selected) {
    *   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.
+   *   A Boolean indicating whether the category should be selected by default.
    */
   function updateCategory($id, $label, $recipients, $reply, $selected) {
     $edit = array();