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

5 files changed, 120 insertions, 37 deletions

diff --git a/modules/statistics/statistics.admin.inc b/modules/statistics/statistics.admin.inc
index 6606b8b95..415fd0054 100644
--- a/modules/statistics/statistics.admin.inc
+++ b/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
+ *   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
+ *   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
+ *   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
+ *   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 $aid
+ *   The unique accesslog ID.
+ *
+ * @return
+ *   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/modules/statistics/statistics.install b/modules/statistics/statistics.install
index 56a7de107..b85743553 100644
--- a/modules/statistics/statistics.install
+++ b/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/modules/statistics/statistics.module b/modules/statistics/statistics.module
index 89cda6dcf..81d24b755 100644
--- a/modules/statistics/statistics.module
+++ b/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.
- *
+ *   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 $dbrows
- *   number of rows to be returned.
+ *   The 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 $path
+ *   The path to generate the link for.
+ * @param $width
+ *   The width to set the displayed text of the path.
+ *
+ * @return
+ *   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 $title
+ *   The text to link to a path; will be truncated to a maximum width of 35.
+ * @param $path
+ *   The path to link to; will default to '/'.
+ *
+ * @return
+ *   An HTML string with $title linked to the $path.
+ */
 function _statistics_format_item($title, $path) {
   $path = ($path ? $path : '/');
   $output  = ($title ? "$title<br />" : '');
diff --git a/modules/statistics/statistics.pages.inc b/modules/statistics/statistics.pages.inc
index bb31f9838..8bd9712f6 100644
--- a/modules/statistics/statistics.pages.inc
+++ b/modules/statistics/statistics.pages.inc
@@ -2,9 +2,16 @@
 
 /**
  * @file
- * User page callbacks for the statistics module.
+ * User page callbacks for the Statistics module.
  */
 
+/**
+ * Page callback: Displays statistics for a node.
+ *
+ * @return
+ *   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 +59,13 @@ 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().
+ */
 function statistics_user_tracker() {
   if ($account = user_load(arg(1))) {
 
diff --git a/modules/statistics/statistics.test b/modules/statistics/statistics.test
index f12490acf..a40ecc80e 100644
--- a/modules/statistics/statistics.test
+++ b/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 {
 
@@ -46,10 +46,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() {
@@ -282,10 +282,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() {
@@ -422,7 +436,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() {