Commit c4a4964b authored by jhodgdon's avatar jhodgdon

Issue #1355712 by izus, kid_icarus, batigolix, gapa, chertzog: API docs cleanup for Poll module

parent 6821b3c3
......@@ -7,6 +7,9 @@
namespace Drupal\poll\Tests;
/**
* Tests the recent poll block.
*/
class PollBlockTest extends PollTestBase {
/**
......@@ -32,6 +35,9 @@ function setUp() {
$this->drupalLogin($admin_user);
}
/**
* Tests creating, viewing, voting on recent poll block.
*/
function testRecentBlock() {
// Set block title to confirm that the interface is available.
$this->drupalPost('admin/structure/block/manage/poll/recent/configure', array('title' => $this->randomName(8)), t('Save block'));
......
......@@ -7,6 +7,9 @@
namespace Drupal\poll\Tests;
/**
* Tests creating a poll.
*/
class PollCreateTest extends PollTestBase {
public static function getInfo() {
return array(
......@@ -16,6 +19,9 @@ public static function getInfo() {
);
}
/**
* Tests creating, listing, editing a new poll.
*/
function testPollCreate() {
$title = $this->randomName();
$choices = $this->_generateChoices(7);
......@@ -57,6 +63,9 @@ function testPollCreate() {
$this->assertTrue(strpos(end($votes), $vote_count) > 0, "Votes saved.");
}
/**
* Tests creating, editing, and closing a poll.
*/
function testPollClose() {
$content_user = $this->drupalCreateUser(array('create poll content', 'edit any poll content', 'access content'));
$vote_user = $this->drupalCreateUser(array('cancel own vote', 'inspect all votes', 'vote on polls', 'access content'));
......
......@@ -7,6 +7,9 @@
namespace Drupal\poll\Tests;
/**
* Tests the removal of poll choices.
*/
class PollDeleteChoiceTest extends PollTestBase {
public static function getInfo() {
return array(
......@@ -16,6 +19,9 @@ public static function getInfo() {
);
}
/**
* Tests removing a choice from a poll.
*/
function testChoiceRemoval() {
// Set up a poll with three choices.
$title = $this->randomName();
......
......@@ -7,6 +7,9 @@
namespace Drupal\poll\Tests;
/**
* Tests the expiration of polls.
*/
class PollExpirationTest extends PollTestBase {
public static function getInfo() {
return array(
......@@ -16,6 +19,9 @@ public static function getInfo() {
);
}
/**
* Tests the expiration of a poll.
*/
function testAutoExpire() {
// Set up a poll.
$title = $this->randomName();
......
......@@ -10,7 +10,7 @@
use Drupal\simpletest\WebTestBase;
/**
* Test adding new choices.
* Tests adding new choices to a poll.
*/
class PollJsAddChoiceTest extends WebTestBase {
......@@ -30,7 +30,7 @@ public static function getInfo() {
}
/**
* Test adding a new choice.
* Tests adding a new choice to a poll.
*/
function testAddChoice() {
$web_user = $this->drupalCreateUser(array('create poll content', 'access content'));
......
......@@ -9,6 +9,9 @@
use Drupal\simpletest\WebTestBase;
/**
* Defines a base class for testing the Poll module.
*/
abstract class PollTestBase extends WebTestBase {
/**
......@@ -116,6 +119,9 @@ function _pollGenerateEdit($title, array $choices, $index = 0) {
return array($edit, count($already_submitted_choices) + count($new_choices));
}
/*
* Generates random choices for the poll.
*/
function _generateChoices($count = 7) {
$choices = array();
for ($i = 1; $i <= $count; $i++) {
......@@ -125,7 +131,7 @@ function _generateChoices($count = 7) {
}
/**
* Assert correct poll choice order in the node form after submission.
* Asserts correct poll choice order in the node form after submission.
*
* Verifies both the order in the DOM and in the 'weight' form elements.
*
......@@ -185,6 +191,9 @@ function assertPollChoiceOrder(array $choices, $index = 0, $preview = FALSE) {
}
}
/**
* Tests updating a poll.
*/
function pollUpdate($nid, $title, $edit) {
// Edit the poll node.
$this->drupalPost('node/' . $nid . '/edit', $edit, t('Save'));
......
......@@ -8,7 +8,7 @@
namespace Drupal\poll\Tests;
/**
* Test poll token replacement in strings.
* Tests poll token replacements in strings.
*/
class PollTokenReplaceTest extends PollTestBase {
public static function getInfo() {
......
......@@ -49,8 +49,10 @@ function setUp() {
}
/**
* Check that anonymous users with same ip cannot vote on poll more than once
* unless user is logged in.
* Checks that anonymous users with the same IP address can only vote once.
*
* Also checks that authenticated users can only vote once, even when the
* user's IP address has changed.
*/
function testHostnamePollVote() {
// Login User1.
......
......@@ -7,6 +7,9 @@
namespace Drupal\poll\Tests;
/**
* Tests voting on a poll.
*/
class PollVoteTest extends PollTestBase {
public static function getInfo() {
return array(
......@@ -20,6 +23,9 @@ function tearDown() {
parent::tearDown();
}
/**
* Tests voting on a poll.
*/
function testPollVote() {
$title = $this->randomName();
$choices = $this->_generateChoices(7);
......
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the poll module.
* Install, update, and uninstall functions for the Poll module.
*/
/**
......
......@@ -2,8 +2,7 @@
/**
* @file
* Enables your site to capture votes on different topics in the form of multiple
* choice questions.
* Collects votes on different topics in the form of multiple choice questions.
*/
use Drupal\node\Node;
......@@ -106,7 +105,14 @@ function poll_menu() {
}
/**
* Callback function to see if a node is acceptable for poll menu items.
* Access callback: Determines if a node is acceptable for poll menu items.
*
* @param $node
* The poll node object.
* @param $perm
* A permission the user must have to view the page.
* @param $inspect_allowvotes
* TRUE if the user can view votes, and FALSE if the user cannot view votes.
*/
function _poll_menu_access($node, $perm, $inspect_allowvotes) {
return user_access($perm) && ($node->type == 'poll') && ($node->allowvotes || !$inspect_allowvotes);
......@@ -125,6 +131,8 @@ function poll_block_info() {
* Implements hook_block_view().
*
* Generates a block containing the latest poll.
*
* @see poll_block_latest_poll_view()
*/
function poll_block_view($delta = '') {
if (user_access('access content')) {
......@@ -342,13 +350,13 @@ function poll_form(Node $node, &$form_state) {
}
/**
* Submit handler to add more choices to a poll form.
* Form submission handler for adding more than two choices to a poll.
*
* This handler is run regardless of whether JS is enabled or not. It makes
* changes to the form state. If the button was clicked with JS disabled, then
* the page is reloaded with the complete rebuilt form. If the button was
* clicked with JS enabled, then ajax_form_callback() calls poll_choice_js() to
* return just the changed part of the form.
* This handler is run regardless of whether JavaScript is enabled. It makes
* changes to the form state. If the button is clicked with JavaScript
* disabled, then the page is reloaded with the complete rebuilt form. If the
* button was clicked with JavaScript enabled, then ajax_form_callback() calls
* poll_choice_js() to return just the changed part of the form.
*/
function poll_more_choices_submit($form, &$form_state) {
// Add one more choice to the form.
......@@ -365,6 +373,11 @@ function poll_more_choices_submit($form, &$form_state) {
$form_state['rebuild'] = TRUE;
}
/**
* Constructs one individual form choice as part of poll node form.
*
* @see poll_form()
*/
function _poll_choice_form($key, $chid = NULL, $value = '', $votes = 0, $weight = 0, $size = 10) {
$form = array(
'#tree' => TRUE,
......@@ -410,12 +423,10 @@ function _poll_choice_form($key, $chid = NULL, $value = '', $votes = 0, $weight
}
/**
* Ajax callback in response to new choices being added to the form.
* Ajax callback for adding new choices to the poll node form.
*
* This returns the new page content to replace the page content made obsolete
* by the form submission.
*
* @see poll_more_choices_submit()
*/
function poll_choice_js($form, $form_state) {
return $form['choice_wrapper']['choice'];
......@@ -426,6 +437,8 @@ function poll_choice_js($form, $form_state) {
*
* Upon preview and final submission, we need to renumber poll choices and
* create a teaser output.
*
* @see poll_teaser()
*/
function poll_node_form_submit($entity_type, $entity, &$form, &$form_state) {
// Renumber choices.
......@@ -607,10 +620,12 @@ function poll_delete($node) {
}
/**
* Return content for 'latest poll' block.
* Returns the content for the 'latest poll' block.
*
* @param Drupal\node\Node $node
* The node entity to load.
*
* @see poll_view_results()
*/
function poll_block_latest_poll_view(Node $node) {
global $user;
......@@ -654,6 +669,8 @@ function poll_block_latest_poll_view(Node $node) {
/**
* Implements hook_view().
*
* @see poll_view_results()
*/
function poll_view($node, $view_mode) {
global $user;
......@@ -672,6 +689,12 @@ function poll_view($node, $view_mode) {
* Creates a simple teaser that lists all the choices.
*
* This is primarily used for RSS.
*
* @param $node
* The poll node object.
*
* @return
* Poll choices in a simple teaser format.
*/
function poll_teaser($node) {
$teaser = NULL;
......@@ -686,11 +709,16 @@ function poll_teaser($node) {
}
/**
* Generates the voting form for a poll.
* Form constructor for the poll voting form.
*
* @ingroup forms
* @see poll_vote()
* @param $node
* The poll node object.
* @param $block
* (optional) TRUE if a poll should be displayed in a block. Defaults to
* FALSE.
* @see phptemplate_preprocess_poll_vote()
* @see poll_vote()
* @ingroup forms
*/
function poll_view_voting($form, &$form_state, $node, $block = FALSE) {
if ($node->choice) {
......@@ -727,7 +755,9 @@ function poll_view_voting($form, &$form_state, $node, $block = FALSE) {
}
/**
* Validation function for processing votes
* Form validation handler for poll_view_voting().
*
* @see poll_vote()
*/
function poll_view_voting_validate($form, &$form_state) {
if ($form_state['values']['choice'] == -1) {
......@@ -736,7 +766,9 @@ function poll_view_voting_validate($form, &$form_state) {
}
/**
* Submit handler for processing a vote.
* Form submission handler for poll_view_voting().
*
* @see poll_view_voting_validate()
*/
function poll_vote($form, &$form_state) {
$node = $form['#node'];
......@@ -785,9 +817,7 @@ function poll_preprocess_block(&$variables) {
}
/**
* Themes the voting form for a poll.
*
* Inputs: $form
* Implements template_preprocess_HOOK() for poll-vote.tpl.php.
*/
function template_preprocess_poll_vote(&$variables) {
$form = $variables['form'];
......@@ -803,6 +833,9 @@ function template_preprocess_poll_vote(&$variables) {
/**
* Generates a graphical representation of the results of a poll.
*
* @see poll_block_latest_poll_view()
* @see poll_view()
*/
function poll_view_results($node, $view_mode, $block = FALSE) {
// Make sure that choices are ordered by their weight.
......@@ -896,13 +929,21 @@ function theme_poll_choices($variables) {
}
/**
* Preprocess the poll_results theme hook.
* Implements template_preprocess_HOOK() for poll-results.tpl.php.
*
* Inputs: $raw_title, $results, $votes, $raw_links, $block, $nid, $vote. The
* $raw_* inputs to this are naturally unsafe; often safe versions are
* made to simply overwrite the raw version, but in this case it seems likely
* that the title and the links may be overridden by the theme layer, so they
* are left in with a different name for that purpose.
* @param $variables
* An associative array containing:
* - raw_title: A string for the title of the poll.
* - results: The results of the poll.
* - votes: The total results in the poll.
* - raw_links: Array containing links in the poll.
* - block: A boolean to define if the poll is a block.
* - nid: The node ID of the poll.
* - vote: The choice number of the current user's vote.
* The raw_* inputs to this are naturally unsafe; often safe versions are
* made to simply overwrite the raw version, but in this case it seems likely
* that the title and the links may be overridden by the theme layer, so they
* are left in with a different name for that purpose.
*
* @see poll-results.tpl.php
* @see poll-results--block.tpl.php
......@@ -917,7 +958,10 @@ function template_preprocess_poll_results(&$variables) {
}
/**
* Builds the cancel form for a poll.
* Form constructor for the poll cancel form.
*
* @param $nid
* The poll node ID.
*
* @ingroup forms
* @see poll_cancel()
......@@ -939,7 +983,7 @@ function poll_cancel_form($form, &$form_state, $nid) {
}
/**
* Submit callback for poll_cancel_form().
* Form submission handler for poll_cancel_form().
*/
function poll_cancel($form, &$form_state) {
global $user;
......
......@@ -2,11 +2,16 @@
/**
* @file
* User page callbacks for the poll module.
* Page callbacks for the Poll module.
*/
/**
* Menu callback to provide a simple list of all polls available.
* Page callback: Displays a simple list of all available polls.
*
* @return
* The HTML for the page that shows the available polls.
*
* @see poll_menu()
*/
function poll_page() {
$polls_per_page = 15;
......@@ -47,7 +52,17 @@ function poll_page() {
}
/**
* Callback for the 'votes' tab for polls you can see other votes on
* Page callback: Displays the 'votes' tab for polls.
*
* This page displays a table containing each vote that has been cast.
*
* @param $node
* The poll node object.
*
* @return
* Render array containing table with votes.
*
* @see poll_menu()
*/
function poll_votes($node) {
$votes_per_page = 20;
......@@ -91,7 +106,17 @@ function poll_votes($node) {
}
/**
* Callback for the 'results' tab for polls you can vote on
* Page callback: Displays the 'results' tab for the current poll.
*
* This tab displays a summary of the votes that have been cast.
*
* @param $node
* The poll node object.
*
* @return
* An array suitable for use by drupal_render().
*
* @see poll_menu()
*/
function poll_results($node) {
drupal_set_title($node->label());
......
Markdown is supported
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