diff --git a/core/modules/statistics/statistics.admin.inc b/core/modules/statistics/statistics.admin.inc index 6606b8b..cefe79b 100644 --- a/core/modules/statistics/statistics.admin.inc +++ b/core/modules/statistics/statistics.admin.inc @@ -6,7 +6,17 @@ */ /** - * Menu callback; presents the "recent hits" page. + * Page callback: Displays recent page accesses. + * + * Callback path: admin/reports/hits + * + * This displays the pages with recent hits in a given time interval. The time + * interval used is the value of the persistent variable + * statistics_flush_accesslog_timer. That value is set on the statistics + * settings form. + * + * @return array + * A render array containing information about the most recent hits. */ function statistics_recent_hits() { $header = array( @@ -45,7 +55,17 @@ function statistics_recent_hits() { } /** - * Menu callback; presents the "top pages" page. + * Page callback: Displays statistics for the "top pages" (most accesses). + * + * Callback path: admin/reports/pages + * + * This displays the pages with the most hits (the "top pages") within a given + * time interval. The time interval used is the value of the persistent variable + * statistics_flush_accesslog_timer. That value is set on the statistics + * settings form. + * + * @return array + * A render array containing information about the the top pages. */ function statistics_top_pages() { $header = array( @@ -90,7 +110,17 @@ function statistics_top_pages() { } /** - * Menu callback; presents the "top visitors" page. + * Page callback: Displays the "top visitors" page. + * + * Callback path: admin/reports/visitors + * + * This displays the pages with the top number of visitors in a given time + * interval. The time interval used is the value of the persistent variable + * statistics_flush_accesslog_timer. That value is set on the statistics + * settings form. + * + * @return array + * A render array containing the top visitors information. */ function statistics_top_visitors() { @@ -143,7 +173,17 @@ function statistics_top_visitors() { } /** - * Menu callback; presents the "referrer" page. + * Page callback: Displays the top referrers in the access logs. + * + * Callback path: admin/reports/referrers + * + * This displays the "referrer" page: a page that shows the top referrers in a + * given time interval. The time interval used is the value of the persistent + * variable statistics_flush_accesslog_timer. That value is set on the + * statistics settings form. + * + * @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 +229,13 @@ function statistics_top_referrers() { } /** - * Menu callback; Displays recent page accesses. + * Page callback: Gathers page access statistics suitable for rendering. + * + * Callback path: admin/reports/access/% + * + * @return array + * A render array containing page access statistics. If information for the + * page was not found, calls drupal_not_found(). */ 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 +279,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.module b/core/modules/statistics/statistics.module index 969a4f4..4158721 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,19 @@ function statistics_cron() { } /** - * Returns all time or today top or last viewed node(s). + * Returns top viewed content of all time, for 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 $dbrows + * @param string $dbfield + * One of: + * - 'totalcount': Show the top viewed content of all time. + * - 'daycount': Show the top viewed content for today. + * - 'timestamp': Show only the last viewed node. + * @param int $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 n.nid, n.title, u.uid, u.name of 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'))) { @@ -291,11 +290,11 @@ function statistics_title_list($dbfield, $dbrows) { * 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". + * An array with three entries: [0]=totalcount, [1]=daycount, [2]=timestamp: + * - totalcount: The total number of times that node has been viewed. + * - daycount: 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. + * - timestamp: The timestamp of when that node was last viewed. */ function statistics_get($nid) { @@ -374,8 +373,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 +389,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
" : ''); diff --git a/core/modules/statistics/statistics.pages.inc b/core/modules/statistics/statistics.pages.inc index 1d91609..fe87d9c 100644 --- a/core/modules/statistics/statistics.pages.inc +++ b/core/modules/statistics/statistics.pages.inc @@ -2,9 +2,18 @@ /** * @file - * User page callbacks for the statistics module. + * User page callbacks for statistics.module. */ +/** + * Page callback: Displays statistics for a node. + * + * Callback path: node/%node/track + * + * @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(). + */ function statistics_node_tracker() { if ($node = node_load(arg(1))) { @@ -52,6 +61,15 @@ function statistics_node_tracker() { } } +/** + * Page callback: Displays statistics for a user. + * + * Callback path: user/%user/track/navigation + * + * @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(). + */ 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 bf3aeac..68016bc 100644 --- a/core/modules/statistics/statistics.test +++ b/core/modules/statistics/statistics.test @@ -6,7 +6,7 @@ */ /** - * Sets up a base class for the Statistics module. + * Defines a base class for testing the Statistics module. */ class StatisticsTestCase extends DrupalWebTestCase { @@ -48,8 +48,8 @@ class StatisticsTestCase extends DrupalWebTestCase { /** * Tests that logging via statistics_exit() works for cached and uncached 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() { @@ -284,10 +284,24 @@ class StatisticsBlockVisitorsTestCase extends StatisticsTestCase { } /** - * Test statistics administration screen. + * Tests the statistics administration screen. */ class StatisticsAdminTestCase extends DrupalWebTestCase { + + /** + * A user that has permissions necessary 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) to access and then verify the access statistics for it. + * + * @var node + */ protected $test_node; public static function getInfo() { @@ -424,7 +438,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() {