diff --git a/modules/statistics/statistics.admin.inc b/modules/statistics/statistics.admin.inc index 6606b8b..1fc1855 100644 --- a/modules/statistics/statistics.admin.inc +++ b/modules/statistics/statistics.admin.inc @@ -6,7 +6,15 @@ */ /** - * Menu callback; presents the "recent hits" page. + * Displays recent page accesses. This is a menu callback. + * + * This is a menu callback to display the pages with recent hits. + * The time interval used is the statistics_flush_accesslog_timer. + * This set on the statistics settings form. + * + * @return array $build + * Returns an associative array that can be rendered with information about + * the most recent hits. */ function statistics_recent_hits() { $header = array( @@ -47,6 +55,17 @@ function statistics_recent_hits() { /** * Menu callback; presents the "top pages" page. */ +/** + * Displays statistices for the "top pages" accesses. This is a menu callback. + * + * This is a menu callback to display the pages with the most hits (the "top + * pages"). The time interval used is the statistics_flush_accesslog_timer. + * This set on the statistics settings form. + * + * @return array $build + * Returns an associative array with the top pages information; this array + * can be rendered. + */ function statistics_top_pages() { $header = array( array('data' => t('Hits'), 'field' => 'hits', 'sort' => 'desc'), @@ -90,7 +109,15 @@ function statistics_top_pages() { } /** - * Menu callback; presents the "top visitors" page. + * Displays the "top visitors" page. This is a menu callback. + * + * This is a menu callback to display the top visitors. The time interval + * used is the statistics_flush_accesslog_timer. This set on the statistics + * settings form. + * + * @return array $build + * Returns an associative array with the top visitors information. This array + * can be rendered. */ function statistics_top_visitors() { @@ -143,7 +170,15 @@ function statistics_top_visitors() { } /** - * Menu callback; presents the "referrer" page. + * Displays the top referrers in the access logs. This is a menu callback. + * + * This is a menu callback to display the "referrer" page. The time interval + * used is the statistics_flush_accesslog_timer. This set on the statistics + * settings form. + * + * @return array $build + * Returns an associative array with the top referrers information. This + * array can be rendered . */ 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 +224,12 @@ function statistics_top_referrers() { } /** - * Menu callback; Displays recent page accesses. + * Displays recent page accesses. This is a menu callback. + * + * @return array $build | drupal_not_found() + * Returns an associative array with the page access statistics that can be + * rendered. If information for the page was not found, returns + * 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 +273,14 @@ function statistics_access_log($aid) { } /** - * Form builder; Configure access logging. + * Form settings for the statistics administration form. + * + * Adds form elements for the statistics administration form, including + * settings for the statistics access log. + * + * @return array $form + * Returns an associative array containing the structure of the statistics + * settings form. * * @ingroup forms * @see system_settings_form() diff --git a/modules/statistics/statistics.install b/modules/statistics/statistics.install index a5dc7f8..44b6bf4 100644 --- a/modules/statistics/statistics.install +++ b/modules/statistics/statistics.install @@ -21,6 +21,9 @@ function statistics_uninstall() { /** * Implements hook_schema(). + * + * @return array $schema + * Returns the associative array with the schema information. */ function statistics_schema() { $schema['accesslog'] = array( diff --git a/modules/statistics/statistics.module b/modules/statistics/statistics.module index 0ba9d7f..e31e534 100644 --- a/modules/statistics/statistics.module +++ b/modules/statistics/statistics.module @@ -2,11 +2,14 @@ /** * @file - * Logs access statistics for your site. + * Logs and displays access statistics for a site. */ /** * Implements hook_help(). + * + * @return string + * Returns HTML with help info. */ function statistics_help($path, $arg) { switch ($path) { @@ -45,7 +48,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; @@ -129,6 +132,9 @@ function statistics_node_view($node, $view_mode) { /** * Implements hook_menu(). + * + * @return array $item + * Returns the associative array $item that has menu items and callback info. */ function statistics_menu() { $items['admin/reports/hits'] = array( @@ -246,15 +252,14 @@ 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 + * @param string $dbfield * one of * - 'totalcount': top viewed content of all time. * - 'daycount': top viewed content for today. * - 'timestamp': last viewed node. - * - * @param $dbrows + * @param int $dbrows * number of rows to be returned. * * @return @@ -371,8 +376,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 | 35 + * The width to set the displayed text of the path + * + * @return link + * Returns the text truncated to the width, linked to the given $path. */ function _statistics_link($path, $width = 35) { $title = drupal_get_path_alias($path); @@ -380,6 +392,17 @@ function _statistics_link($path, $width = 35) { return l($title, $path); } +/** + * Create a link for text to a path, truncating width of the text if needed. + * * + * @param string $title + * The text to link to a path; will be truncated to a max width of 35. + * @param string $path | '/' + * The path to link to; will default to '/'. + * + * @return string $output + * Returns the HTML with $title linked to the $path. + */ function _statistics_format_item($title, $path) { $path = ($path ? $path : '/'); $output = ($title ? "$title
" : ''); diff --git a/modules/statistics/statistics.pages.inc b/modules/statistics/statistics.pages.inc index bb31f98..4b5f7c9 100644 --- a/modules/statistics/statistics.pages.inc +++ b/modules/statistics/statistics.pages.inc @@ -5,6 +5,14 @@ * User page callbacks for the statistics module. */ +/** + * Displays statistics for a node. This is a menu callback. + * + * @return array $build | drupal_not_found() + * Returns $build, an associative array containing node statistics. This + * associative array can be rendered. 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 +60,14 @@ function statistics_node_tracker() { } } +/** + * Displays statistics for a user. This is a menu callback. + * + * @return array $build | drupal_not_found() + * Returns $build, an associative array containing user statistics. This + * associative array can be rendered. 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/modules/statistics/statistics.test b/modules/statistics/statistics.test index 126828f..4cd61eb 100644 --- a/modules/statistics/statistics.test +++ b/modules/statistics/statistics.test @@ -2,14 +2,19 @@ /** * @file - * Tests for statistics.module. + * Tests for the statistics module. */ /** - * Sets up a base class for the Statistics module. + * Sets up a base class for testing the statistics module. */ class StatisticsTestCase extends DrupalWebTestCase { + /** + * Set up the test class; initialize data needed for testing. + * + * @see DrupalWebTestCase::setUp() + */ function setUp() { parent::setUp('statistics'); @@ -48,10 +53,13 @@ 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 { + /** + * Return the name, description, and group info for this test case. + */ public static function getInfo() { return array( 'name' => 'Statistics logging tests', @@ -60,6 +68,11 @@ class StatisticsLoggingTestCase extends DrupalWebTestCase { ); } + /** + * Set up the test class; initialize data needed for testing. + * + * @see DrupalWebTestCase::setUp() + */ function setUp() { parent::setUp('statistics'); @@ -123,6 +136,9 @@ class StatisticsLoggingTestCase extends DrupalWebTestCase { * Tests that report pages render properly, and that access logging works. */ class StatisticsReportsTestCase extends StatisticsTestCase { + /** + * Return the name, description, and group info for this test case. + */ public static function getInfo() { return array( 'name' => 'Statistics reports tests', @@ -210,9 +226,12 @@ class StatisticsReportsTestCase extends StatisticsTestCase { } /** - * Tests that the visitor blocking functionality works. + * Tests that visitor blocking functionality works. */ class StatisticsBlockVisitorsTestCase extends StatisticsTestCase { + /** + * Return the name, description, and group info for this test case. + */ public static function getInfo() { return array( 'name' => 'Top visitor blocking', @@ -260,12 +279,27 @@ 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 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; + /** + * Return the name, description, and group info for this test case. + */ public static function getInfo() { return array( 'name' => 'Test statistics admin.', @@ -274,6 +308,11 @@ class StatisticsAdminTestCase extends DrupalWebTestCase { ); } + /** + * Set up the test class; initialize data needed for testing. + * + * @see DrupalWebTestCase::setUp() + */ function setUp() { parent::setUp('statistics'); $this->privileged_user = $this->drupalCreateUser(array('access statistics', 'administer statistics', 'view post access counter', 'create page content')); @@ -403,6 +442,9 @@ class StatisticsAdminTestCase extends DrupalWebTestCase { * Test statistics token replacement in strings. */ class StatisticsTokenReplaceTestCase extends StatisticsTestCase { + /** + * Return the name, description, and group info for this test case. + */ public static function getInfo() { return array( 'name' => 'Statistics token replacement',