1 files changed, 39 insertions, 20 deletions

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 />" : '');