diff --git a/core/modules/statistics/statistics.admin.inc b/core/modules/statistics/statistics.admin.inc index 6606b8b..70d9763 100644 --- a/core/modules/statistics/statistics.admin.inc +++ b/core/modules/statistics/statistics.admin.inc @@ -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() diff --git a/core/modules/statistics/statistics.install b/core/modules/statistics/statistics.install index a5dc7f8..5ee20dc 100644 --- a/core/modules/statistics/statistics.install +++ b/core/modules/statistics/statistics.install @@ -2,7 +2,7 @@ /** * @file - * Install, update and uninstall functions for the statistics module. + * Install, update, and uninstall functions for the Statistics module. */ /** diff --git a/core/modules/statistics/statistics.module b/core/modules/statistics/statistics.module index af1f833..d9e9b49 100644 --- a/core/modules/statistics/statistics.module +++ b/core/modules/statistics/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
" : ''); @@ -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(). */ diff --git a/core/modules/statistics/statistics.pages.inc b/core/modules/statistics/statistics.pages.inc index 1d91609..1b776d1 100644 --- a/core/modules/statistics/statistics.pages.inc +++ b/core/modules/statistics/statistics.pages.inc @@ -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))) { diff --git a/core/modules/statistics/statistics.test b/core/modules/statistics/statistics.test index 62cec24..d19fd92 100644 --- a/core/modules/statistics/statistics.test +++ b/core/modules/statistics/statistics.test @@ -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() {