Skip to content
GitLab
Commit dd1cc680 authored by Dries Buytaert's avatar Dries Buytaert
Browse files

- Patch #1332636 by sven.lauer: clean up API docs for contact module.

parent d91203fe
Hide whitespace changes
Inline Side-by-side
core/modules/contact/contact.admin.inc
View file @ dd1cc680
......@@ -2,11 +2,15 @@
/**
* @file
* Admin page callbacks for the contact module.
* Admin page callbacks for the Contact module.
*/
/**
* Categories/list tab.
* Page callback: Lists contact categories.
*
* Path: admin/structure/contact
*
* @see contact_menu()
*/
function contact_category_list() {
$header = array(
......@@ -53,7 +57,27 @@ function contact_category_list() {
}
/**
* Category edit page.
* Form constructor for the category edit form.
*
* Paths:
* - admin/structure/contact/add
* - admin/structure/contact/edit/%contact
*
* @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_menu()
* @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 +141,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 +170,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 +195,15 @@ function contact_category_edit_form_submit($form, &$form_state) {
}
/**
* Form builder for deleting a contact category.
* Form constructor for the contact category deletion form.
*
* Path: admin/structure/contact/delete/%contact
*
* @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 +223,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'];
......
core/modules/contact/contact.module
View file @ dd1cc680
......@@ -107,13 +107,14 @@ function contact_menu() {
}
/**
* Menu access callback for a user's personal contact form.
* Access callback: Checks access for a user's personal contact form.
*
* Path: user/%user/contact
*
* @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.
*
* @see contact_menu()
*/
function _contact_personal_tab_access($account) {
global $user;
......@@ -148,10 +149,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 +213,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) {
$form['contact'] = array(
......@@ -239,6 +243,8 @@ function contact_user_presave(&$edit, $account) {
* 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(
......
core/modules/contact/contact.pages.inc
View file @ dd1cc680
......@@ -2,14 +2,18 @@
/**
* @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.
*
* Path: contact
*
* @see contact_menu()
* @see contact_site_form_validate()
* @see contact_site_form_submit()
* @ingroup forms
*/
function contact_site_form($form, &$form_state) {
global $user;
......@@ -112,6 +116,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 +130,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 +174,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 +256,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 +267,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;
......
core/modules/contact/contact.test
View file @ dd1cc680
<?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.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment