Commit 0016283b authored by jhodgdon's avatar jhodgdon

Issue #1313510 by NROTC_Webmaster, oriol_e9g, aenw: API docs cleanup for Statistics module

parent f61cb9bc
......@@ -2,11 +2,18 @@
/**
* @file
* Admin page callbacks for the statistics module.
* Admin page callbacks for the Statistics module.
*/
/**
* Menu callback; presents the "recent hits" page.
* Page callback: Displays the "recent hits" page.
*
* This displays the pages with recent hits in a given time interval that
* haven't been flushed yet. The flush interval is set on the statistics
* settings form, but is dependent on cron running.
*
* @return array
* A render array containing information about the most recent hits.
*/
function statistics_recent_hits() {
$header = array(
......@@ -45,7 +52,14 @@ function statistics_recent_hits() {
}
/**
* Menu callback; presents the "top pages" page.
* Page callback: Displays statistics for the "top pages" (most accesses).
*
* This displays the pages with the most hits (the "top pages") within a given
* time period that haven't been flushed yet. The flush interval is set on the
* statistics settings form, but is dependent on cron running.
*
* @return array
* A render array containing information about the the top pages.
*/
function statistics_top_pages() {
$header = array(
......@@ -57,7 +71,8 @@ function statistics_top_pages() {
$query = db_select('accesslog', 'a', array('target' => 'slave'))->extend('PagerDefault')->extend('TableSort');
$query->addExpression('COUNT(path)', 'hits');
// MAX(title) avoids having empty node titles which otherwise causes duplicates in the top pages list
// MAX(title) avoids having empty node titles which otherwise causes
// duplicates in the top pages list.
$query->addExpression('MAX(title)', 'title');
$query->addExpression('AVG(timer)', 'average_time');
$query->addExpression('SUM(timer)', 'total_time');
......@@ -90,7 +105,14 @@ function statistics_top_pages() {
}
/**
* Menu callback; presents the "top visitors" page.
* Page callback: Displays the "top visitors" page.
*
* This displays the pages with the top number of visitors in a given time
* interval that haven't been flushed yet. The flush interval is set on the
* statistics settings form, but is dependent on cron running.
*
* @return array
* A render array containing the top visitors information.
*/
function statistics_top_visitors() {
......@@ -143,7 +165,14 @@ function statistics_top_visitors() {
}
/**
* Menu callback; presents the "referrer" page.
* Page callback: Displays the "top referrers" in the access logs.
*
* This displays the pages with the top referrers in a given time interval that
* haven't been flushed yet. The flush interval is set on the statistics
* settings form, but is dependent on cron running.
*
* @return array
* A render array containing the top referrers information.
*/
function statistics_top_referrers() {
drupal_set_title(t('Top referrers in the past %interval', array('%interval' => format_interval(variable_get('statistics_flush_accesslog_timer', 259200)))), PASS_THROUGH);
......@@ -189,7 +218,14 @@ function statistics_top_referrers() {
}
/**
* Menu callback; Displays recent page accesses.
* Page callback: Gathers page access statistics suitable for rendering.
*
* @param int $aid
* The unique accesslog ID.
*
* @return array
* A render array containing page access statistics. If information for the
* page was not found, drupal_not_found() is called.
*/
function statistics_access_log($aid) {
$access = db_query('SELECT a.*, u.name FROM {accesslog} a LEFT JOIN {users} u ON a.uid = u.uid WHERE aid = :aid', array(':aid' => $aid))->fetch();
......@@ -233,7 +269,7 @@ function statistics_access_log($aid) {
}
/**
* Form builder; Configure access logging.
* Form constructor for the statistics administration form.
*
* @ingroup forms
* @see system_settings_form()
......
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the statistics module.
* Install, update, and uninstall functions for the Statistics module.
*/
/**
......
......@@ -2,7 +2,7 @@
/**
* @file
* Logs access statistics for your site.
* Logs and displays access statistics for a site.
*/
/**
......@@ -45,7 +45,7 @@ function statistics_help($path, $arg) {
/**
* Implements hook_exit().
*
* This is where statistics are gathered on page accesses.
* Gathers statistics for page accesses.
*/
function statistics_exit() {
global $user;
......@@ -249,20 +249,20 @@ function statistics_cron() {
}
/**
* Returns all time or today top or last viewed node(s).
* Returns the most viewed content of all time, today, or the last-viewed node.
*
* @param $dbfield
* one of
* - 'totalcount': top viewed content of all time.
* - 'daycount': top viewed content for today.
* - 'timestamp': last viewed node.
* @param string $dbfield
* The database field to use, one of:
* - 'totalcount': Integer that shows the top viewed content of all time.
* - 'daycount': Integer that shows the top viewed content for today.
* - 'timestamp': Integer that shows only the last viewed node.
* @param int $dbrows
* The number of rows to be returned.
*
* @param $dbrows
* number of rows to be returned.
*
* @return
* A query result containing n.nid, n.title, u.uid, u.name of the selected node(s)
* or FALSE if the query could not be executed correctly.
* @return SelectQuery|FALSE
* A query result containing the node ID, title, user ID that owns the node,
* and the username for the selected node(s), or FALSE if the query could not
* be executed correctly.
*/
function statistics_title_list($dbfield, $dbrows) {
if (in_array($dbfield, array('totalcount', 'daycount', 'timestamp'))) {
......@@ -288,14 +288,15 @@ function statistics_title_list($dbfield, $dbrows) {
* Retrieves a node's "view statistics".
*
* @param $nid
* node ID
* The node ID.
*
* @return
* An array with three entries: [0]=totalcount, [1]=daycount, [2]=timestamp
* - totalcount: count of the total number of times that node has been viewed.
* - daycount: count of the total number of times that node has been viewed "today".
* For the daycount to be reset, cron must be enabled.
* - timestamp: timestamp of when that node was last viewed.
* An associative array containing:
* - totalcount: Integer for the total number of times the node has been
* viewed.
* - daycount: Integer for the total number of times the node has been viewed
* "today". For the daycount to be reset, cron must be enabled.
* - timestamp: Integer for the timestamp of when the node was last viewed.
*/
function statistics_get($nid) {
......@@ -374,8 +375,15 @@ function statistics_block_view($delta = '') {
}
/**
* It is possible to adjust the width of columns generated by the
* statistics module.
* Generates a link to a path, truncating the displayed text to a given width.
*
* @param string $path
* The path to generate the link for.
* @param int $width
* The width to set the displayed text of the path.
*
* @return string
* A string as a link, truncated to the width, linked to the given $path.
*/
function _statistics_link($path, $width = 35) {
$title = drupal_get_path_alias($path);
......@@ -383,6 +391,17 @@ function _statistics_link($path, $width = 35) {
return l($title, $path);
}
/**
* Formats an item for display, including both the item title and the link.
*
* @param string $title
* The text to link to a path; will be truncated to a maximum width of 35.
* @param string $path
* The path to link to; will default to '/'.
*
* @return string
* An HTML string with $title linked to the $path.
*/
function _statistics_format_item($title, $path) {
$path = ($path ? $path : '/');
$output = ($title ? "$title<br />" : '');
......@@ -428,6 +447,7 @@ function statistics_ranking() {
function statistics_update_index() {
variable_set('node_cron_views_scale', 1.0 / max(1, db_query('SELECT MAX(totalcount) FROM {node_counter}')->fetchField()));
}
/**
* Implements hook_preprocess_block().
*/
......
......@@ -2,9 +2,19 @@
/**
* @file
* User page callbacks for the statistics module.
* User page callbacks for the Statistics module.
*/
/**
* Page callback: Displays statistics for a node.
*
* @return array
* A render array containing node statistics. If information for the node was
* not found, this will deliver a page not found error via
* drupal_not_found().
*
* @see statistics_menu()
*/
function statistics_node_tracker() {
if ($node = node_load(arg(1))) {
......@@ -52,6 +62,16 @@ function statistics_node_tracker() {
}
}
/**
* Page callback: Displays statistics for a user.
*
* @return array
* A render array containing user statistics. If information for the user was
* not found, this will deliver a page not found error via
* drupal_not_found().
*
* @see statistics_menu()
*/
function statistics_user_tracker() {
if ($account = user_load(arg(1))) {
......
......@@ -2,11 +2,11 @@
/**
* @file
* Tests for statistics.module.
* Tests for the Statistics module.
*/
/**
* Sets up a base class for the Statistics module.
* Defines a base class for testing the Statistics module.
*/
class StatisticsTestCase extends DrupalWebTestCase {
......@@ -51,10 +51,10 @@ class StatisticsTestCase extends DrupalWebTestCase {
}
/**
* Tests that logging via statistics_exit() works for cached and uncached pages.
* Tests that logging via statistics_exit() works for all pages.
*
* Subclass DrupalWebTestCase rather than StatisticsTestCase, because we want
* to test requests from an anonymous user.
* We subclass DrupalWebTestCase rather than StatisticsTestCase, because we
* want to test requests from an anonymous user.
*/
class StatisticsLoggingTestCase extends DrupalWebTestCase {
public static function getInfo() {
......@@ -294,10 +294,24 @@ class StatisticsBlockVisitorsTestCase extends StatisticsTestCase {
}
/**
* Test statistics administration screen.
* Tests the statistics administration screen.
*/
class StatisticsAdminTestCase extends DrupalWebTestCase {
/**
* A user that has permission to administer and access statistics.
*
* @var object|FALSE
*
* A fully loaded user object, or FALSE if user creation failed.
*/
protected $privileged_user;
/**
* A page node for which to check access statistics.
*
* @var object
*/
protected $test_node;
public static function getInfo() {
......@@ -443,7 +457,7 @@ class StatisticsAdminTestCase extends DrupalWebTestCase {
}
/**
* Test statistics token replacement in strings.
* Tests statistics token replacement in strings.
*/
class StatisticsTokenReplaceTestCase extends StatisticsTestCase {
public static function getInfo() {
......
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