Index: coder.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/coder.module,v
retrieving revision 1.88.2.17
diff -u -r1.88.2.17 coder.module
--- coder.module	26 Dec 2007 22:03:53 -0000	1.88.2.17
+++ coder.module	8 Jan 2008 01:41:09 -0000
@@ -1,7 +1,9 @@
 <?php
 // $Id: coder.module,v 1.88.2.17 2007/12/26 22:03:53 douggreen Exp $
 
-/** @file
+/**
+ * @file
+ * 
  * Developer Module that assists with code review and version upgrade that
  * supports a plug-in extensible hook system so contributed modules can
  * define additional review standards.
@@ -11,6 +13,9 @@
  * - Handle text in a secure fashion - http://drupal.org/node/28984
  * - Converting 4.6.x modules to 4.7.x - http://drupal.org/node/22218
  * - Converting 4.7.x modules to 5.x - http://drupal.org/node/64279
+ * - Converting 5.x modules to 6.x - http://drupal.org/node/114774
+ * - Comment Standards - http://drupal.org/node/1354
+ * - SQL coding conventions - http://drupal.org/node/2497
  *
  * Credit also to dries:
  * - http://cvs.drupal.org/viewcvs/drupal/drupal/scripts/code-style.pl
@@ -31,14 +36,17 @@
       return;
   } 
 } 
+
 /**
- * Get all of the code review modules
+ * Get all of the code review modules, including contributions.
  */
 function _coder_reviews() {
-  // get the contributed module review definitions
   return module_invoke_all('reviews');
 }
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_reviews() {
   global $_coder_reviews;
   if (!isset($_coder_reviews)) {
@@ -132,6 +140,9 @@
 
 /**
  * Implementation of hook_form_alter().
+ * 
+ * This function modifies the module display view by adding a
+ * Coder Review link to every module description.
  */
 function coder_form_alter(&$form, $form_state, $form_id) {
   if ($form_id == 'system_modules') {
@@ -147,19 +158,40 @@
 }
 
 /**
- * Helper functions for settings form
+ * Helper functions for settings form.
  */
 function _coder_default_reviews() {
   return drupal_map_assoc(array('style', 'sql', 'comment', 'security'));
 }
 
+/**
+ * Build settings form API array for coder.
+ * 
+ * Generates a form with the default reviews and default modules/themes to
+ * run Coder on.
+ * 
+ * @note
+ *   Actual forms may have additional sections added to them, this
+ *   is simply a base.
+ * 
+ * @param $settings
+ *   Settings array for coder in the format of _coder_get_default_settings().
+ * @param $system
+ *   Is filled with lookup array of module and theme information, in form
+ *   string theme/module name => boolean TRUE if checked by coder already.
+ * @param $files
+ *   Is filled with associative array of files, in form
+ *   string theme/module name => string filename to check.
+ * @return
+ *   Array for form API for the settings box.
+ */
 function _coder_settings_form($settings, &$system, &$files) {
-  // add the javascript
+  // Add the javascript.
   $path = drupal_get_path('module', 'coder');
   drupal_add_js($path .'/coder.js');
 
-  // create the list of review options from the coder review plug-ins
-  // maintain a secondary list based on #title only, to make sorting possible
+  // Create the list of review options from the coder review plug-ins.
+  // Maintain a secondary list based on #title only, to make sorting possible.
   $reviews = _coder_reviews();
   foreach ($reviews as $name => $review) {
     $review_options[$name] = isset($review['#link']) ? l($review['#title'], $review['#link']) : $review['#title'];
@@ -169,13 +201,13 @@
     $review_sort[$name] = $review['#title'];
   }
 
-  // sort the reviews by #title
+  // Sort the reviews by #title.
   asort($review_sort);
   foreach ($review_sort as $name => $review) {
     $review_sort[$name] = $review_options[$name];
   }
 
-  // what reviews should be used?
+  // What reviews should be used?
   $form['coder_reviews_group'] = array(
     '#type' => 'fieldset',
     '#title' => t('Reviews'),
@@ -189,7 +221,7 @@
     '#default_value' => $settings['coder_reviews'],
   );
 
-  // what severities should be used?
+  // What severities should be used?
   $form['coder_reviews_group']['coder_severity'] = array(
     '#type' => 'radios',
     '#options' => array(
@@ -201,7 +233,7 @@
     '#default_value' => $settings['coder_severity'],
   );
   
-  // get the modules and theme
+  // Get the modules and theme.
   $sql = 'SELECT name, filename, type, status FROM {system} WHERE type=\'module\' OR type=\'theme\' ORDER BY weight ASC, filename ASC';
   $result = db_query($sql);
   $system_modules = array();
@@ -227,14 +259,15 @@
   }
   asort($system_links);
 
-  // display what to review options
+  // Display what to review options.
   $form['coder_what'] = array(
     '#type' => 'fieldset',
     '#title' => t('What to review'),
     '#collapsible' => true,
     '#collapsed' => false,
   );
-  $form['coder_what']['coder_active_modules'] = array( // NOTE: should rename var
+  // NOTE: Should rename var.
+  $form['coder_what']['coder_active_modules'] = array(
     '#type' => 'checkbox',
     '#default_value' => isset($settings['coder_active_modules']) ? $settings['coder_active_modules'] : 0,
     '#title' => t('active modules and themes'),
@@ -257,7 +290,7 @@
     );
   }
 
-  // display the modules in a fieldset
+  // Display the modules in a fieldset.
   $form['coder_what']['coder_modules'] = array(
     '#type' => 'fieldset',
     '#title' => t('Select Specific Modules'),
@@ -289,7 +322,7 @@
     $modules = isset($settings['coder_modules']) && is_array($settings['coder_modules']) ? $settings['coder_modules'] : array();
   }
 
-  // display the themes in a fieldset
+  // Display the themes in a fieldset.
   $form['coder_what']['coder_themes'] = array(
     '#type' => 'fieldset',
     '#title' => t('Select Specific Themes'),
@@ -349,6 +382,12 @@
   return $form;
 }
 
+/**
+ * Format checkbox field into columns.
+ * 
+ * @param $form
+ *   Form sub-array to render, usually supplied as callback.
+ */
 function theme_coder_checkboxes($form) {
   $total = 0;
   foreach ($form as $element_id => $element) {
@@ -374,7 +413,7 @@
 }
 
 /**
- * Implementation of settings page for Drupal 5
+ * Implementation of settings page for Drupal 5.
  */
 function coder_admin_settings() {
   $settings = _coder_get_default_settings();
@@ -383,11 +422,25 @@
   return system_settings_form($form);
 }
 
+/**
+ * Callback function for settings page in Drupal 5.
+ */
 function coder_settings_form_submit(&$form, &$form_state) {
   variable_set('coder_modules', _coder_settings_array($form, 'module'));
   variable_set('coder_themes', _coder_settings_array($form, 'theme'));
 }
 
+/**
+ * Generate settings array for either modules or themes.
+ * 
+ * @param $form_values
+ *   Form array passed to submit function (note: entries that are processed.
+ *   are removed for efficiency's sake).
+ * @param $type
+ *   String type to generate settings for, either 'module' or 'theme'.
+ * @return 
+ *   Settings lookup array in form module/theme name => 1
+ */
 function _coder_settings_array(&$form_values, $type) {
   $typekey = "coder_{$type}s-";
   $typelen = strlen($typekey);
@@ -405,7 +458,7 @@
 }
 
 /**
- * Implementation of code review page
+ * Implementation of code review page.
  */
 function coder_page() {
   $output  = '<div class="coder-disclaimer">'. coder_help('coder#disclaimer', array()) .'</div>';
@@ -413,12 +466,25 @@
   return $output;
 }
 
+/**
+ * Returns a active settings array for coder.
+ * 
+ * @note
+ *   The name is a misnomer, but is a largely correct characterization
+ *   for most of Coder's settings as the variables usually do not exist.
+ * 
+ * @param $args
+ *   String settings argument, can be 'settings', 'active', 'core', 'all'
+ *   and 'default'.
+ * @return
+ *   Associative array of settings in form setting name => setting value.
+ */
 function _coder_get_default_settings($args = 'default') {
   $settings['coder_reviews'] = variable_get('coder_reviews', _coder_default_reviews());
   $settings['coder_severity'] = variable_get('coder_severity', SEVERITY_NORMAL);
   $settings['coder_cache'] = variable_get('coder_cache', 1);
 
-  // determine any options based on the passed in URL,
+  // Determine any options based on the passed in URL.
   switch ($args) {
     case 'settings':
       $settings['coder_includes'] = 1;
@@ -449,17 +515,26 @@
 
     default:
       $settings['coder_includes'] = 1;
-      // TODO: does this need to go into coder_themes sometimes?
+      // TODO: Does this need to go into coder_themes sometimes?
       $settings['coder_modules'] = array($args => $args);
       break;
   }
   return $settings;
 }
 
+/**
+ * Implementation of hook_validate().
+ */
 function coder_page_form_validate(&$form, &$form_state) {
   variable_set('_coder_form', $form);
 }
 
+/**
+ * Implementation of hook_form().
+ * 
+ * This implements coder's main form, in which a user can select reviews
+ * and modules/themes to run them on.
+ */
 function coder_page_form() {
   // HELP: is there a better way to get these from the validate handler?
   $form_values = variable_get('_coder_form', array());
@@ -478,7 +553,7 @@
     }
   }
 
-  // get this once - list of the reviews to perform
+  // Get this once: list of the reviews to perform.
   $reviews = array();
   $avail_reviews = _coder_reviews();
   $selected_reviews = $settings['coder_reviews'];
@@ -489,11 +564,11 @@
   }
 
   if ($coder_form = _coder_settings_form($settings, $system, $files)) {
-    // add style sheet
+    // Add style sheet.
     $path = drupal_get_path('module', 'coder');
     drupal_add_css($path .'/coder.css', 'module');
 
-    // code review non-module core files
+    // Code review non-module core files.
     $module_weight = 0;
     if (isset($settings['coder_core']) && $settings['coder_core']) {
       $coder_args = array(
@@ -523,13 +598,14 @@
       _coder_page_form_includes($form, $coder_args, 'core_includes', $includefiles, 0);
     }
 
-    // loop through the selected modules and themes
+    // Loop through the selected modules and themes.
     if (isset($system)) {
-      $dups = array(); // used to avoid duplicate includes
+      // Used to avoid duplicate includes.
+      $dups = array();
       $stats = array();
       foreach ($system as $name => $checked) {
         if ($checked) {
-          // process this one file
+          // Process this one file.
           $filename = $files[$name];
           if (!$filename) {
             drupal_set_message(t('Code Review file for %module not found', array('%module' => $name)));
@@ -544,7 +620,7 @@
           $stats[$filename] = $results['#stats'];
           unset($results['#stats']);
 
-          // output the results in a collapsible fieldset
+          // Output the results in a collapsible fieldset.
           $form[$name] = array(
             '#type' => 'fieldset',
             '#title' => $filename,
@@ -563,10 +639,10 @@
             '#weight' => -1,
           );
 
-          // process the same directory include files
+          // Process the same directory include files.
           if (!empty($settings['coder_includes'])) {
-            // NOTE: convert to the realpath here so drupal_system_listing
-            // doesn't return additional paths (i.e., try "module").
+            // NOTE: Convert to the realpath here so drupal_system_listing.
+            // Doesn't return additional paths (i.e., try "module").
             $path = str_replace('\\', '/', dirname(realpath($filename)));
             $offset = strpos($path, dirname($filename));
             if (!isset($dups[$path])) {
@@ -605,7 +681,7 @@
       }
     }
 
-    // prepend the settings form
+    // Prepend the settings form.
     $form['settings'] = array(
       '#type' => 'fieldset',
       '#title' => t('Selection Form'),
@@ -626,6 +702,24 @@
   return $form;
 }
 
+/**
+ * Add results to form array for display on form page.
+ * 
+ * @param $form
+ *   Form array variable to be modified.
+ * @param $coder_args
+ *   Coder settings, see do_coder_reviews() for details.
+ * @param $name
+ *   Name of form element.
+ * @param $files
+ *   Array of file objects to check and display the results of, see
+ *   file_scan_directory().
+ * @param $offset
+ *   Integer offset to munge filenames with.
+ * @return
+ *   Statistics array in form: string filename => array value of
+ *   '#stats' from do_coder_reviews().
+ */
 function _coder_page_form_includes(&$form, $coder_args, $name, $files, $offset) {
   $stats = array();
   $coder_args['#name'] = $name;
@@ -637,7 +731,7 @@
     $stats[$filename] = $results['#stats'];
     unset($results['#stats']);
 
-    // output the results in a collapsible fieldset
+    // Output the results in a collapsible fieldset.
     $form[$name][$filename] = array(
       '#type' => 'fieldset',
       '#title' => $filename,
@@ -659,6 +753,9 @@
   return $stats;
 }
 
+/**
+ * Return last modification timestamp of coder and all of its dependencies.
+ */
 function _coder_modified() {
   static $_coder_mtime;
   if (!isset($_coder_mtime)) {
@@ -675,9 +772,24 @@
   return $_coder_mtime;
 }
 
+/**
+ * Perform batch coder reviews for multiple files.
+ * 
+ * @param $coder_args
+ *   Array of coder arguments, valid arguments are:
+ *     - '#reviews' => array list of reviews to perform, see _coder_reviews();
+ *     - '#severity' => integer magic number, see constants SEVERITY_*;
+ *     - '#filename' => string filename to check,
+ * @return
+ *   Array of results, in form:
+ *     - '#stats' => Array with error counts for all severities, in form
+ *         'minor' => integer count, 'normal' => integer count;
+ *         'critical' => integer count;
+ *     - integer ID => HTML error for display.
+ */
 function do_coder_reviews($coder_args) {
   if ($use_cache = variable_get('coder_cache', 1)) {
-    // cache the results because:
+    // Cache the results because...
     $cache_key = 'coder:'.  implode(':', array_keys($coder_args['#reviews'])) .  $coder_args['#severity'] .':'. $coder_args['#filename'];
     $cache_mtime = filemtime(realpath($coder_args['#filename']));
     if ($cache_results = cache_get($cache_key)) {
@@ -691,7 +803,7 @@
   $stats = array('minor' => 0, 'normal' => 0, 'critical' => 0);
   $results['#stats'] = $stats;
 
-  // skip php include files when the user requested severity is above minor
+  // Skip php include files when the user requested severity is above minor.
   if (isset($coder_args['#php_minor']) && drupal_substr($coder_args['#filename'], -4) == '.php') {
     if ($coder_args['#severity'] > 1) {
       $results['#stats'] = $stats;
@@ -699,9 +811,9 @@
     }
   }
 
-  // read the file
+  // Read the file.
   if (_coder_read_and_parse_file($coder_args)) {
-    // do all of the code reviews
+    // Do all of the code reviews.
     foreach ($coder_args['#reviews'] as $review) {
       if ($result = do_coder_review($coder_args, $review)) {
         foreach ($stats as $key => $value) {
@@ -712,7 +824,7 @@
       }
     }
 
-    // sort the results
+    // Sort the results.
     ksort($results, SORT_NUMERIC);
     $results['#stats'] = $stats;
   }
@@ -720,7 +832,7 @@
     _coder_error_msg($results, t('Could not read the file'), 'critical');
   }
 
-  // save the results in the cache
+  // Save the results in the cache.
   if ($use_cache) {
     $cache_results = array(
       'mtime' => $cache_mtime,
@@ -732,10 +844,22 @@
   return $results;
 }
 
+/**
+ * Parse and read a file into a format easy to validate.
+ * 
+ * @param $coder_args
+ *   Coder arguments array variable to add file lines of code (with
+ *   trailing newlines. The following array indices are added: '#all_lines',
+ *   '#php_lines', '#allphp_lines', '#html_lines', '#quote_lines',
+ *   '#doublequote_lines', '#comment_lines'. Their names should be
+ *   self explanatory.
+ * @return
+ *   Integer 1 if success.
+ */
 function _coder_read_and_parse_file(&$coder_args) {
-  // get the path to the module file
+  // Get the path to the module file.
   if ($filepath = realpath($coder_args['#filename'])) {
-    // read the file
+    // Read the file.
     $content = file_get_contents($filepath) ."\n";
     $content_length = drupal_strlen($content);
 
@@ -764,22 +888,24 @@
     $this_doublequote_lines = '';
     $this_comment_lines = '';
 
-    // parse the file:
-    // - strip comments
-    // - strip quote content // - strip stuff not in php // - break into lines
+    // Parse the file:
+    // - Strip comments,
+    // - Strip quote content,
+    // - Strip stuff not in php,
+    // - Break into lines.
     $lineno = 0;
     for ($pos = 0; $pos < $content_length; $pos ++) {
-      // get the current character
+      // Get the current character.
       $char = $content[$pos];
       if ($char == "\n") {
-        if ($in_comment && $in_comment == '/') { // end C++ style comments on newline
+        if ($in_comment && $in_comment == '/') { // End C++ style comments on newline.
           $in_comment = 0;
         }
 
-        // assume that html inside quotes doesn't span newlines
+        // Assume that html inside quotes doesn't span newlines.
         $in_quote_html = 0;
 
-        // remove blank lines now, so we avoid processing them over-and-over
+        // Remove blank lines now, so we avoid processing them over-and-over.
         if ($this_all_lines != '') {
           if (trim($this_all_lines) != '') {
             $all_lines[$lineno] = $this_all_lines;
@@ -804,7 +930,7 @@
           }
         }
 
-        // save this line and start a new line
+        // Save this line and start a new line.
         $lineno ++;
         $this_all_lines = '';
         $this_php_lines = '';
@@ -822,8 +948,8 @@
       $this_all_lines .= $char;
 
       if ($in_php || $in_allphp) {
-        // when in a quoted string, look for the trailing quote
-        // strip characters in the string, replacing with '' or ""
+        // When in a quoted string, look for the trailing quote
+        // strip characters in the string, replacing with '' or "".
         if ($in_quote) {
           if ($in_backslash) {
             $in_backslash = 0;
@@ -850,7 +976,7 @@
             $in_quote_html = 0;
           }
           $this_allphp_lines .= $char;
-          unset($char); // NOTE: trailing char output with starting one
+          unset($char); // NOTE: Trailing char output with starting one.
         }
 
         elseif ($in_heredoc) {
@@ -871,7 +997,7 @@
           unset($char);
         }
 
-        // look for the ending php tag 
+        // Look for the ending php tag.
         elseif ($char == '?' && $content[$pos + 1] == '>') {
           unset($char);
           $in_php = 0;
@@ -880,7 +1006,7 @@
           $pos ++;
         }
 
-        // when in a comment look for the trailing comment
+        // When in a comment look for the trailing comment.
         elseif ($in_comment) {
           $this_comment_lines .= $char;
           if ($in_comment == '*' && $char == '*' && $content[$pos + 1] == '/') {
@@ -889,7 +1015,7 @@
             $this_comment_lines .= '/';
             $pos ++;
           }
-          unset($char); // don't add comments to php output
+          unset($char); // Don't add comments to php output.
         }
 
         else {
@@ -918,8 +1044,8 @@
                 unset($char);
                 $this_all_lines .= '<<';
 
-                // get the heredoc word
-                // read until the end-of-line
+                // Get the heredoc word.
+                // Read until the end-of-line.
                 for ($pos += 3; $pos < $content_length; $pos ++) {
                   $char = $content[$pos];
                   if ($char == "\n") {
@@ -935,7 +1061,7 @@
                 }
                 $heredoc = '';
 
-                // replace heredoc's with an empty string
+                // Replace heredoc's with an empty string.
                 $this_php_lines .= '\'\'';
                 $this_allphp_lines .= '\'\'';
                 unset($char);
@@ -966,7 +1092,7 @@
               }
               break;
             }
-            // FALTHROUGH
+            // Fallthrough.
           default:
             $this_html_lines .= $char;
             break;
@@ -993,7 +1119,7 @@
       $comment_lines[$lineno] = $this_comment_lines;
     }
 
-    // add the files lines to the arguments
+    // Add the files lines to the arguments.
     $coder_args['#all_lines'] = $all_lines;
     $coder_args['#php_lines'] = $php_lines;
     $coder_args['#allphp_lines'] = $allphp_lines;
@@ -1005,8 +1131,18 @@
   }
 }
 
+/**
+ * Return the integer severity magic number for a string severity.
+ *
+ * @param $severity_name
+ *   String severity name 'minor', 'normal', or 'critical'.
+ * @param $default_value
+ *   Integer magic number to use if severity string is not recognized.
+ * @return
+ *   Integer magic number, see SEVERITY_* constants.
+ */
 function _coder_severity($severity_name, $default_value = SEVERITY_NORMAL) {
-  // NOTE: implemented this way in hopes that it is faster than a php switch
+  // NOTE: Implemented this way in hopes that it is faster than a php switch.
   if (!isset($severity_names)) {
     $severity_names = array(
       'minor' => SEVERITY_MINOR,
@@ -1020,41 +1156,64 @@
   return $default_value;
 }
 
+/**
+ * Return string severity for a given error.
+ * 
+ * @param $coder_args
+ *   Coder settings array, see do_coder_reviews().
+ * @param $review
+ *   Review array, see hook_reviews(), contains rule arrays.
+ * @param $rule
+ *   Rule array that was triggered, see individual entries from hook_reviews().
+ * @return
+ *   String severity of error.
+ */
 function _coder_severity_name($coder_args, $review, $rule) {
-  // NOTE: warnings in php includes are suspicious because
-  // php includes are frequently 3rd party products
+  // NOTE: Warnings in php includes are suspicious because
+  // php includes are frequently 3rd party products.
   if (isset($coder_args['#php_minor']) && substr($coder_args['#filename'], -4) == '.php') {
     return 'minor';
   }
 
-  // get the severity as defined by the rule
+  // Get the severity as defined by the rule.
   if (isset($rule['#severity'])) {
     return $rule['#severity'];
   }
 
-  // if it's not defined in the rule, then it can be defined by the review
+  // If it's not defined in the rule, then it can be defined by the review.
   if (isset($review['#severity'])) {
     return $review['#severity'];
   }
 
-  // use the default
+  // Use the default.
   return 'normal';
 }
 
+/**
+ * Perform code review for a review array.
+ * 
+ * @param $coder_args
+ *   Array coder settings, must have been prepared with _coder_read_and_parse_file(),
+ *   see do_coder_reviews() for format.
+ * @param $review
+ *   Review array, see hook_review().
+ * @return
+ *   Array results, see do_coder_reviews() return value for format.
+ */
 function do_coder_review($coder_args, $review) {
   $results = array('#stats' => array('minor' => 0, 'normal' => 0, 'critical' => 0));
   if ($review['#rules']) {
-    // get the review's severity, used when the rule severity is not defined
+    // Get the review's severity, used when the rule severity is not defined.
     $default_severity = isset($review['#severity']) ? _coder_severity($review['#severity']) : SEVERITY_NORMAL;
 
     foreach ($review['#rules'] as $rule) {
-      // perform the review if above the user requested severity
+      // Perform the review if above the user requested severity.
       $severity = _coder_severity(isset($rule['#severity']) ? $rule['#severity'] : '', $default_severity);
       if ($severity >= $coder_args['#severity']) {
-        if (isset($rule['#original'])) { // deprecated
+        if (isset($rule['#original'])) { // Deprecated.
           $lines = $coder_args['#all_lines'];
         }
-        elseif (isset($rule['#source'])) { // all, html, comment, allphp or php
+        elseif (isset($rule['#source'])) { // Values: all, html, comment, allphp or php.
           $source = '#'. $rule['#source'] .'_lines';
           $lines = $coder_args[$source];
         }
@@ -1083,6 +1242,20 @@
   return $results;
 }
 
+/**
+ * Implements do_coder_review_* for regex match.
+ * 
+ * @param $coder_args
+ *   Coder settings array variable, see do_coder_review() for format.
+ * @param $review
+ *   Review array the current rule belongs to, used by _coder_severity_name().
+ * @param $rule
+ *   Rule array being checked.
+ * @param $lines
+ *   Pertinent source file lines according to rule's '#source' value.
+ * @param $results
+ *   Results array variable to save errors to.
+ */
 function do_coder_review_regex(&$coder_args, $review, $rule, $lines, &$results) {
   if (isset($rule['#value'])) {
     $regex = '/'. $rule['#value'] .'/';
@@ -1095,7 +1268,7 @@
     $not_regex = isset($rule['#not']) ? '/'. $rule['#not'] .'/i' : '';
     $never_regex = isset($rule['#never']) ? '/'. $rule['#never'] .'/i' : '';
     foreach ($lines as $lineno => $line) {
-      // some rules apply only within certain functions
+      // Some rules apply only within certain functions.
       if ($function_regex) {
         if (preg_match('/function (\w+)\(/', $line, $match)) {
           $current_function = $match[1];
@@ -1109,7 +1282,7 @@
       }
 
       if (preg_match($regex, $line, $matches)) {
-        // don't match some regex's
+        // Don't match some regex's.
         if ($not_regex) {
           foreach ($matches as $match) {
             if (preg_match($not_regex, $match)) {
@@ -1131,12 +1304,28 @@
   }
 }
 
+/**
+ * Builds an error message based on the rule that failed and other information.
+ * 
+ * @param $results
+ *   Results array variable to save errors to.
+ * @param $rule
+ *   Rule array that triggered the error.
+ * @param $severity_name
+ *   String severity of error as detected by _coder_severity_name().
+ * @param $lineno
+ *   Line number of error.
+ * @param $line
+ *   Contents of line that triggered error.
+ * @param $original
+ *   Deprecated.
+ */
 function _coder_error(&$results, $rule, $severity_name, $lineno = -1, $line = '', $original = '') {
   if (isset($rule['#warning_callback'])) {
     if (function_exists($rule['#warning_callback'])) {
       $warning = $rule['#warning_callback']();
     }
-    else { // if this happens, there is an error in the rule definition
+    else { // If this happens, there is an error in the rule definition.
       $warning = t('please <a href="@report">report</a> this !warning',
         array(
           '@report' => 'http://drupal.org/node/add/project_issue/coder/bug',
@@ -1152,6 +1341,23 @@
   return _coder_error_msg($results, $warning, $severity_name, $lineno, $line);
 }
 
+/**
+ * Does the actual saving of error to results array and generating its
+ * unique numeric id.
+ * 
+ * @param $results
+ *   Results array variable to save errors to.
+ * @param $warning
+ *   Warning array/string to be themed, returned from '#warning_callback' or
+ *   is a translated string from the rule. See theme_coder_warning() for
+ *   array format.
+ * @param $severity_name
+ *   String severity of error.
+ * @param $lineno
+ *   Integer line number error occured on.
+ * @param $line
+ *   String line contents.
+ */
 function _coder_error_msg(&$results, $warning, $severity_name, $lineno = -1, $line = '') {
   // Note: The use of the $key allows multiple errors on one line.
   // This assumes that no line of source has more than 10000 lines of code
@@ -1163,7 +1369,10 @@
 }
 
 /**
- * Searches for a string.
+ * Search for a string.
+ * 
+ * @note
+ *   See do_coder_review_regex() for arguments.
  */
 function do_coder_review_grep(&$coder_args, $review, $rule, $lines, &$results) {
   if (isset($rule['#value'])) {
@@ -1178,7 +1387,10 @@
 }
 
 /**
- * Searches for potentially missing string.
+ * Search for potentially missing string.
+ * 
+ * @note
+ *   See do_coder_review_regex() for arguments.
  */
 function do_coder_review_grep_invert(&$coder_args, $review, $rule, $lines, &$results) {
   if (isset($rule['#value'])) {
@@ -1192,6 +1404,12 @@
   }
 }
 
+/**
+ * Allow for an arbitrary callback function to perform a review.
+ * 
+ * @note
+ *   See do_coder_review_regex() for arguments.
+ */
 function do_coder_review_callback(&$coder_args, $review, $rule, $lines, &$results) {
   if ($function = $rule['#value']) {
     if (function_exists($function)) {
@@ -1206,10 +1424,12 @@
  * Uses strpos() and stripos() if available for performance optimization or
  * preg_match().
  * 
- * @param string $line Haystack
- * @param array $rule Rule to process
- * 
- * @return bool True if needle is in haystack.
+ * @param $line
+ *   Haystack.
+ * @param $rule
+ *   Rule to process.
+ * @return
+ *   TRUE if needle is in haystack.
  */
 function _coder_search_string($line, $rule) {
   static $php5;
@@ -1223,26 +1443,29 @@
     }
   }
   
-  // case-sensitive search with strpos() (supported everywhere)
+  // Case-sensitive search with strpos() (supported everywhere).
   if (isset($rule['#case-sensitive'])) {
     return strpos($line, $rule['#value']) !== false;
   }
   
-  // case-insensitive search with stripos() (supported in PHP 5)
+  // Case-insensitive search with stripos() (supported in PHP 5).
   if ($php5 && !isset($rule['#case-sensitive'])) {
     return stripos($line, $rule['#value']) !== false;
   }
   
-  // case-insensitive search
+  // Case-insensitive search.
   $regex = '/'. preg_quote($rule['#value']) .'/i';
   return preg_match($regex, $line);
 }
 
+/**
+ * Return true if $module is in Drupal core.
+ */
 function _coder_is_drupal_core($module) {
   static $core;
   if (!isset($core)) {
     $core = array(
-      // modules
+      // Modules:
       'aggregator' => 1,
       'block' => 1,
       'blog' => 1,
@@ -1277,7 +1500,7 @@
       'upload' => 1,
       'user' => 1,
 
-      // themes
+      // Themes:
       'bluemarine' => 1,
       'chameleon' => 1,
       'garland' => 1,
@@ -1289,10 +1512,11 @@
   return isset($core[$module->name]) ? 1 : 0;
 }
 
+// Theming functions
+
 /**
- * Theming functions below...
+ * Implementation of hook_theme().
  */
-
 function coder_theme() {
   return array(
     'coder' => array('arguments' => array('name', 'filename', 'results')),
@@ -1302,6 +1526,16 @@
   );
 }
 
+/**
+ * Format coder form and results.
+ * 
+ * @param $name
+ *   Name of module/theme checked, not used.
+ * @param $filename
+ *   String filename checked.
+ * @param $results
+ *   Array list of results HTML to display. See do_coder_reviews() for format.
+ */
 function theme_coder($name, $filename, $results) {
   $output = '<div class="coder"><h2>'. basename($filename) .'</h2>';
   if (!empty($results)) {
@@ -1311,8 +1545,23 @@
   return $output;
 }
 
+/**
+ * Format a coder warning to be included in results.
+ * 
+ * @param $warning
+ *   Either summary warning description, or an array in format:
+ *     - '#warning' => Summary warning description;
+ *     - '#description' => Detailed warning description;
+ *     - '#link' => Link to an explanatory document.
+ * @param $severity_name
+ *   String severity name.
+ * @param $lineno
+ *   Integer line number of error.
+ * @param $line
+ *   String contents of line.
+ */
 function theme_coder_warning($warning, $severity_name, $lineno = 0, $line = '') {
-  // Extract description from warning
+  // Extract description from warning.
   if (is_array($warning)) {
     $description = isset($warning['#description']) ? $warning['#description'] : '';
     $link = $warning['#link'];
@@ -1341,10 +1590,24 @@
   return '<div class="'. $class .'">'. $img . $warning .'</div>';
 }
 
+/**
+ * Format link to Drupal API.
+ * 
+ * @param $function
+ *   Function to link to.
+ * @param $version
+ *   Version to link to.
+ */
 function theme_drupalapi($function, $version = '') {
   return l($function, "http://api.drupal.org/api/function/$function/$version");
 }
 
+/**
+ * Format link to PHP documentation.
+ * 
+ * @param $function
+ *   Function to link to.
+ */
 function theme_phpapi($function) {
   return l($function, "http://us.php.net/$function");
 }
Index: includes/coder_47.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_47.inc,v
retrieving revision 1.14.2.1
diff -u -r1.14.2.1 coder_47.inc
--- includes/coder_47.inc	7 Dec 2007 17:38:12 -0000	1.14.2.1
+++ includes/coder_47.inc	8 Jan 2008 01:53:31 -0000
@@ -1,12 +1,17 @@
 <?php
 // $Id: coder_47.inc,v 1.14.2.1 2007/12/07 17:38:12 douggreen Exp $
 
-/** @file
+/** 
+ * @file
+ * 
  * This include file implements coder functionality for 4.6 -> 4.7 upgrades
  *
- * Todo: The rules for this review have not yet been defined.
+ * @todo The rules for this review have not yet been defined.
  */ 
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_47_reviews() {
   $rules = array(
     array(
Index: includes/coder_50.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_50.inc,v
retrieving revision 1.21.2.3
diff -u -r1.21.2.3 coder_50.inc
--- includes/coder_50.inc	7 Dec 2007 17:38:12 -0000	1.21.2.3
+++ includes/coder_50.inc	8 Jan 2008 01:53:29 -0000
@@ -1,10 +1,15 @@
 <?php
 // $Id: coder_50.inc,v 1.21.2.3 2007/12/07 17:38:12 douggreen Exp $
 
-/** @file
- * This include file implements coder functionality for 4.7 -> 5.0 upgrades
+/** 
+ * @file
+ * 
+ * This include file implements coder functionality for 4.7 -> 5.0 upgrades.
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_50_reviews() {
   $rules = array(
     array(
@@ -76,9 +81,8 @@
 }
 
 /**
- * Define the rule callbacks
+ * Define the rule callbacks for 5.x, see do_coder_review_callback()
  */
-
 function _coder_50_callback(&$coder_args, $review, $rule, $lines, &$results) {
   // only perform this check on module's (not includes)
   $filename = $coder_args['#filename'];
Index: includes/coder_6x.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_6x.inc,v
retrieving revision 1.17.2.31
diff -u -r1.17.2.31 coder_6x.inc
--- includes/coder_6x.inc	11 Dec 2007 15:37:17 -0000	1.17.2.31
+++ includes/coder_6x.inc	8 Jan 2008 01:53:34 -0000
@@ -1,10 +1,15 @@
 <?php
 // $Id: coder_6x.inc,v 1.17.2.31 2007/12/11 15:37:17 snpower Exp $
 
-/** @file
- * This include file implements coder functionality for 5.x -> 6.x upgrades
+/** 
+ * @file
+ * 
+ * This include file implements coder functionality for 5.x -> 6.x upgrades.
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_6x_reviews() {
   $argex = '(((\$?)[a-zA-Z_]+((\([^)]*\))|\[[^\]]*\])?)|[0-9]+(\.[0-9]*)?|\'\'|"")';
   $rules = array(
@@ -416,6 +421,9 @@
   return array('upgrade6x' => $review);
 }
 
+/**
+ * Define the rule callbacks for 6.x, see do_coder_review_callback()
+ */
 function _coder_6x_callback(&$coder_args, $review, $rule, $lines, &$results) {
   // only perform this check on module's (not includes)
   $filename = $coder_args['#filename'];
@@ -466,10 +474,6 @@
 }
 
 /**
- * Define the rule callbacks
- */
-
-/**
  * Define the warning callbacks
  */
 
Index: includes/coder_comment.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_comment.inc,v
retrieving revision 1.1.4.1
diff -u -r1.1.4.1 coder_comment.inc
--- includes/coder_comment.inc	21 Nov 2007 10:41:04 -0000	1.1.4.1
+++ includes/coder_comment.inc	8 Jan 2008 01:53:27 -0000
@@ -1,10 +1,15 @@
 <?php
 // $Id: coder_comment.inc,v 1.1.4.1 2007/11/21 10:41:04 snpower Exp $ 
 
-/** @file
+/** 
+ * @file
+ * 
  * This include file implements coder functionality for comments
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_comment_reviews() {
   $rules = array(
     array(
Index: includes/coder_security.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_security.inc,v
retrieving revision 1.15.2.3
diff -u -r1.15.2.3 coder_security.inc
--- includes/coder_security.inc	7 Dec 2007 17:38:12 -0000	1.15.2.3
+++ includes/coder_security.inc	8 Jan 2008 01:53:24 -0000
@@ -1,12 +1,17 @@
 <?php
 // $Id: coder_security.inc,v 1.15.2.3 2007/12/07 17:38:12 douggreen Exp $
 
-/** @file
- * This include file implements coder functionality for Drupal Standards
+/** 
+ * @file
+ * 
+ * This include file implements coder functionality for Drupal Standards.
  *
- * Todo: The rules for this review are not yet complete.
+ * @todo The rules for this review are not yet complete.
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_security_reviews() {
   $table = '\{[A-Za-z_]+\}'; // table-regex
   $rules = array(
@@ -49,7 +54,7 @@
 
 
 /**
- * Define the warning callbacks
+ * Define the rule callbacks
  */
 
 /* function _coder_security_callback(&$coder_args, $review, $rule, $lines, &$results) {
Index: includes/coder_sql.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/Attic/coder_sql.inc,v
retrieving revision 1.1.4.6
diff -u -r1.1.4.6 coder_sql.inc
--- includes/coder_sql.inc	24 Sep 2007 19:59:47 -0000	1.1.4.6
+++ includes/coder_sql.inc	8 Jan 2008 01:53:15 -0000
@@ -1,10 +1,15 @@
 <?php
 // $Id: coder_sql.inc,v 1.1.4.6 2007/09/24 19:59:47 douggreen Exp $
 
-/** @file
+/**
+ * @file
+ * 
  * This include file implements coder functionality for SQL strings
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_sql_reviews() {
   $table = '\{[A-Za-z_]+\}'; // table-regex
   $bad = '[A-Za-z_]+';
Index: includes/coder_style.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/includes/coder_style.inc,v
retrieving revision 1.16.2.6
diff -u -r1.16.2.6 coder_style.inc
--- includes/coder_style.inc	23 Dec 2007 12:58:45 -0000	1.16.2.6
+++ includes/coder_style.inc	8 Jan 2008 01:53:05 -0000
@@ -1,12 +1,17 @@
 <?php
 // $Id: coder_style.inc,v 1.16.2.6 2007/12/23 12:58:45 douggreen Exp $
 
-/** @file
+/**
+ * @file
+ * 
  * This include file implements coder functionality for Drupal Standards
  *
- * Todo: The rules for this review are not yet complete.
+ * @todo The rules for this review are not yet complete.
  */
 
+/**
+ * Implementation of hook_reviews().
+ */
 function coder_style_reviews() {
   $br = 'br';
   $rules = array(
@@ -127,9 +132,8 @@
 }
 
 /**
- * Define the rule callbacks
+ * Define the rule callbacks for style
  */
-
 function _coder_style_callback(&$coder_args, $review, $rule, $lines, &$results) {
   for ($lineno = -1; $last = array_slice($lines, $lineno); $lineno --) {
     $lastline = $last[0];
Index: scripts/coder_format/coder_format.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/scripts/coder_format/coder_format.inc,v
retrieving revision 1.2.4.1
diff -u -r1.2.4.1 coder_format.inc
--- scripts/coder_format/coder_format.inc	4 Sep 2007 11:23:23 -0000	1.2.4.1
+++ scripts/coder_format/coder_format.inc	8 Jan 2008 01:51:35 -0000
@@ -2,26 +2,31 @@
 // $Id: coder_format.inc,v 1.2.4.1 2007/09/04 11:23:23 douggreen Exp $
 
 /**
- * Recursively process .module and .inc files in directory.
+ * Recursively process .module and .inc files in directory with coder_format_file().
  * 
- * @param bool undo Whether to undo batch replacements.
+ * @param $root
+ *   Path to root directory for Drupal installation.
+ * @param $undo
+ *   Boolean whether or not to undo batch replacements.
+ * @param $file_inc
+ *   Path to Drupal's file.inc, default is $root/includes/file.inc
  */
 function coder_format_recursive($root, $undo = false, $file_inc = null) {
-  // Convert Windows paths
+  // Convert Windows paths.
   $root = str_replace("\\", '/', $root);
   
-  // Check if directory exists
+  // Check if directory exists.
   if (!file_exists($root)) {
     echo 'ERROR: '. $root .' does not exist!';
     return;
   }
   
-  // Trim root directory
+  // Trim root directory.
   if (substr($root, -1) == '/') {
     $root = substr($root, 0, -1);
   }
   
-  // Include Drupal's file.inc
+  // Include Drupal's file.inc.
   if (!isset($file_inc)) {
     if (!file_exists($root .'/includes/file.inc')) {
       echo 'ERROR: '. $root .'/includes/file.inc not found!';
@@ -37,12 +42,12 @@
   require_once (!isset($file_inc) ? $root .'/includes/file.inc' : $file_inc);
   
   if (!$undo) {
-    // Fetch files to process
+    // Fetch files to process.
     $mask = '.module$|.inc$|.install|.profile$';
     $nomask = array('.', '..', 'CVS', '.svn');
     $files = file_scan_directory($root, $mask, $nomask, 0, true);
     foreach ($files as $file) {
-      // file_copy() assigns $file->filename by reference
+      // file_copy() assigns $file->filename by reference.
       $sourcefile = $file->filename;
       echo $file->filename ."\n";
       file_copy($file->filename, $file->filename .'.coder.orig');
@@ -50,7 +55,7 @@
     }
   }
   else {
-    // Fetch files to process
+    // Fetch files to process.
     $mask = '.coder.orig$';
     $nomask = array('.', '..', 'CVS', '.svn');
     $files = file_scan_directory($root, $mask, $nomask, 0, true);
@@ -64,32 +69,39 @@
 
 /**
  * Reads, processes and writes the source code from and to a file.
+ * 
+ * @param $sourcefile
+ *   Path to source file to read code from.
+ * @param $targetfile
+ *   Target path to write formatted source code to.
+ * @return
+ *   TRUE if successful.
  */
 function coder_format_file($sourcefile = null, $targetfile = null) {
   if (!isset($sourcefile) || !isset($targetfile)) {
     return;
   }
   
-  // Read source code from source file
+  // Read source code from source file.
   $fd = fopen($sourcefile, 'r');
   $code = fread($fd, filesize($sourcefile));
   fclose($fd);
   
   if ($code !== false) {
-    // Preprocess source code
+    // Preprocess source code.
     $code = coder_exec_processors($code, 'coder_preprocessor');
     
-    // Process source code
+    // Process source code.
     $code = coder_format_string($code);
     
-    // Postprocess source code
+    // Postprocess source code.
     $code = coder_exec_processors($code, 'coder_postprocessor');
     
-    // Fix beginning and end of code
+    // Fix beginning and end of code.
     $code = coder_trim_php($code);
     
     if ($code !== false) {
-      // Write formatted source code to target file
+      // Write formatted source code to target file.
       $fd = fopen($targetfile, 'w');
       $status = fwrite($fd, $code);
       fclose($fd);
@@ -155,16 +167,16 @@
  *      Controls formatting of ? and : for inline ifs until a ; (semicolon) is
  *      processed.
  *
- * @param string $code
+ * @param $code
  *      The source code to format.
  *
- * @return mixed $result
- *      Returns the formatted code or false if it fails.
+ * @return
+ *      The formatted code or false if it fails.
  */
 function coder_format_string($code = '') {
   global $_coder_indent;
   
-  // indent controls
+  // Indent controls:
   $_coder_indent  = 0;
   $in_case        = false;
   $parenthesis    = 0;
@@ -174,7 +186,7 @@
   $first_php_tag  = true;
   $in_do_while    = false;
   
-  // whitespace controls
+  // Whitespace controls:
   $in_object   = false;
   $in_at       = false;
   $in_php      = false;
@@ -196,13 +208,13 @@
   
   foreach ($tokens as $token) {
     if (is_string($token)) {
-      // simple 1-character token
+      // Simple 1-character token.
       $text = trim($token);
       switch ($text) {
         case '{':
           // Write curly braces at the end of lines followed by a line break if
           // not in quotes (""), object ($foo->{$bar}) or in variables (${foo}).
-          // [T_DOLLAR_OPEN_CURLY_BRACES exists but is never assigned.]
+          // (T_DOLLAR_OPEN_CURLY_BRACES exists but is never assigned.)
           if (!$in_quote && !$in_object && substr(rtrim($result), -1) != '$') {
             if ($in_case) {
               ++$braces_in_case;
@@ -223,14 +235,14 @@
             }
             --$_coder_indent;
             if ($braces_in_case < 0) {
-              // Decrease indent if last case in a switch is not terminated
+              // Decrease indent if last case in a switch is not terminated.
               --$_coder_indent;
               $in_case = false;
               $braces_in_case = 0;
             }
             $result = rtrim($result);
             if (substr($result, -1) != '{') {
-              // Avoid line break in empty curly braces
+              // Avoid line break in empty curly braces.
               $result .= coder_br();
             }
             $result .= $text . coder_br();
@@ -303,7 +315,7 @@
         
         case '.':
           if (substr(rtrim($result), -1) == "'" || substr(rtrim($result), -1) == '"') {
-            // Write string concatenation character directly after strings
+            // Write string concatenation character directly after strings.
             $result = rtrim($result) . $text .' ';
           }
           else {
@@ -334,7 +346,7 @@
 
         case '-':
           $result = rtrim($result);
-          // Do not add a space before negative numbers or variables
+          // Do not add a space before negative numbers or variables.
           if (substr($result, -1) == '>' || substr($result, -1) == '=' || substr($result, -1) == ',' || substr($result, -1) == ':') {
             $result .= ' '. $text;
           }
@@ -344,12 +356,12 @@
           break;
         
         case '"':
-          // toggle quote if the char is not escaped
+          // Toggle quote if the char is not escaped.
           if (rtrim($result) != "\\") {
             $in_quote = $in_quote ? false : true;
           }
           if (substr($result, -3) == ' . ') {
-            // Write string concatenation character directly before strings
+            // Write string concatenation character directly before strings.
             $result = rtrim($result);
           }
           $result .= $text;
@@ -364,10 +376,10 @@
       // If we get here, then we have found not a single char, but a token.
       // See <http://www.php.net/manual/en/tokens.php> for a reference.
       
-      // Fetch token array
+      // Fetch token array.
       list($id, $text) = $token;
       
-      // Debugging
+      // Debugging:
       /*
       if ($lasttoken[0] == T_WHITESPACE) {
         $result .= token_name($id);
@@ -376,14 +388,14 @@
       
       switch ($id) {
         case T_ARRAY:
-          // Write array in lowercase
+          // Write array in lowercase.
           $result .= strtolower(trim($text));
           break;
         
         case T_OPEN_TAG:
         case T_OPEN_TAG_WITH_ECHO:
           $in_php = true;
-          // Add a line break between two PHP tags
+          // Add a line break between two PHP tags.
           if (substr(rtrim($result), -2) == '?>') {
             $result .= coder_br();
           }
@@ -399,7 +411,7 @@
         
         case T_CLOSE_TAG:
           $in_php = false;
-          // Remove preceding line break for inline PHP output in HTML
+          // Remove preceding line break for inline PHP output in HTML.
           if (substr(rtrim($result), -1) == ';' || substr(rtrim($result), -1) == ':') {
             $result = rtrim($result) .' ';
           }
@@ -413,21 +425,21 @@
         
         case T_CONSTANT_ENCAPSED_STRING:
           if (substr($result, -2) == '. ') {
-            // Write string concatenation character directly before strings
+            // Write string concatenation character directly before strings.
             $result = rtrim($result);
           }
-          // Move on to T_STRING / T_VARIABLE
+          // Move on to T_STRING / T_VARIABLE.
         case T_STRING:
         case T_VARIABLE:
           if ($in_object || $in_at) {
-            // No space after object operator ($foo->bar) and error suppression (@function())
+            // No space after object operator ($foo->bar) and error suppression (@function()).
             $result = rtrim($result) . trim($text);
             $in_object = false;
             $in_at = false;
           }
           else {
             if (!in_array($lasttoken[0], array(T_ARRAY_CAST, T_BOOL_CAST, T_DOUBLE_CAST, T_INT_CAST, T_OBJECT_CAST, T_STRING_CAST, T_UNSET_CAST))) {
-              // Insert a space after right parenthesis, but not after type casts
+              // Insert a space after right parenthesis, but not after type casts.
               coder_add_space($result);
             }
             $result .= trim($text);
@@ -439,18 +451,18 @@
           break;
         
         case T_WHITESPACE:
-          // Avoid duplicate line feeds outside arrays
+          // Avoid duplicate line feeds outside arrays.
           $c = $parenthesis ? 0 : 1;
           
           for ($c, $cc = substr_count($text, chr(10)); $c < $cc; ++$c) {
             if ($parenthesis) {
-              // Add extra indent for each parenthesis in multiline definitions (f.e. arrays)
+              // Add extra indent for each parenthesis in multiline definitions (f.e. arrays).
               $_coder_indent = $_coder_indent + $parenthesis;
               $result = rtrim($result) . coder_br();
               $_coder_indent = $_coder_indent - $parenthesis;
             }
             else {
-              // Discard any whitespace, just insert a line break
+              // Discard any whitespace, just insert a line break.
               $result .= coder_br();
             }
           }
@@ -470,7 +482,7 @@
         case T_INCLUDE:
         case T_INCLUDE_ONCE:
           coder_add_space($result);
-          // Append a space
+          // Append a space.
           $result .= trim($text) .' ';
           break;
         
@@ -481,17 +493,17 @@
         
         case T_WHILE:
           if ($in_do_while) {
-            // Write while after right parenthesis for do {...} while()
+            // Write while after right parenthesis for do {...} while().
             $result = rtrim($result) .' ';
             $in_do_while = false;
           }
-          // Append a space
+          // Append a space.
           $result .= trim($text) .' ';
           break;
         
         case T_ELSE:
         case T_ELSEIF:
-          // Write else and else if to a new line
+          // Write else and else if to a new line.
           $result = rtrim($result) . coder_br() . trim($text) .' ';
           break;
         
@@ -501,20 +513,20 @@
           $result = rtrim($result);
           if (!$in_case) {
             $in_case = true;
-            // Add a line break between cases
+            // Add a line break between cases.
             if (substr($result, -1) != '{') {
               $result .= coder_br();
             }
           }
           else {
-            // Decrease current indent to align multiple cases
+            // Decrease current indent to align multiple cases.
             --$_coder_indent;
           }
           $result .= coder_br() . trim($text) .' ';
           break;
         
         case T_BREAK:
-          // Write break to a new line
+          // Write break to a new line.
           $result = rtrim($result) . coder_br() . trim($text);
           if ($in_case && !$braces_in_case) {
             --$_coder_indent;
@@ -526,7 +538,7 @@
         case T_CONTINUE:
           coder_add_space($result);
           $result .= trim($text) .' ';
-          // Decrease indent only if we're not in a control structure inside a case
+          // Decrease indent only if we're not in a control structure inside a case.
           if ($in_case && !$braces_in_case) {
             --$_coder_indent;
             $in_case = false;
@@ -535,7 +547,7 @@
         
         case T_FUNCTION:
         case T_CLASS:
-          // Write function and class to new lines
+          // Write function and class to new lines.
           $result = rtrim($result);
           if (substr($result, -1) == '}') {
             $result .= coder_br();
@@ -544,7 +556,7 @@
           break;
         
         case T_EXTENDS:
-          // Add space before and after 'extends'
+          // Add space before and after 'extends'.
           $result = rtrim($result);
           $result .= ' '. trim($text) .' ';
           break;
@@ -575,9 +587,9 @@
         case T_SR:
         case T_SR_EQUAL:
         case T_XOR_EQUAL:
-          // Surround operators with spaces
+          // Surround operators with spaces.
           if (substr($result, -1) != ' ') {
-            // $result must not be trimmed to allow multi-line if-clauses
+            // $result must not be trimmed to allow multi-line if-clauses.
             $result .= ' ';
           }
           $result .= trim($text) .' ';
@@ -587,10 +599,10 @@
         case T_ML_COMMENT:
         case T_DOC_COMMENT:
           if (substr($text, 0, 3) == '/**') {
-            // Prepend a new line
+            // Prepend a new line.
             $result = rtrim($result) . coder_br() . coder_br();
             
-            // Remove carriage returns
+            // Remove carriage returns.
             $text = str_replace("\r", '', $text);
             
             $lines = explode("\n", $text);
@@ -613,7 +625,7 @@
                 $result .= ' *'. coder_br();
               }
               
-              // Add one space indent to get ' *[...]'
+              // Add one space indent to get ' *[...]'.
               if ($l > 0) {
                 $result .= ' ';
               }
@@ -626,13 +638,13 @@
           else {
             $result .= trim($text);
             if ($parenthesis) {
-              // Add extra indent for each parenthesis in multiline definitions (f.e. arrays)
+              // Add extra indent for each parenthesis in multiline definitions (f.e. arrays).
               $_coder_indent = $_coder_indent + $parenthesis;
               $result = rtrim($result) . coder_br();
               $_coder_indent = $_coder_indent - $parenthesis;
             }
             else {
-              // Discard any whitespace, just insert a line break
+              // Discard any whitespace, just insert a line break.
               $result .= coder_br();
             }
           }
@@ -657,7 +669,7 @@
           break;
       }
 
-      // Store last token
+      // Store last token.
       $lasttoken = $token;
     }
   }
@@ -667,11 +679,10 @@
 /**
  * Generate a line feed including current line indent.
  *
- * @param bool $add_indent
- *      Whether to add current line indent after line feed.
- *
- * @return string
- *      The resulting string.
+ * @param $add_indent
+ *   Whether to add current line indent after line feed.
+ * @return
+ *   The resulting string.
  */
 function coder_br($add_indent = true) {
   global $_coder_indent;
@@ -689,11 +700,10 @@
  * A conditional space is needed after a right parenthesis of an if statement
  * that is not followed by curly braces.
  * 
- * @param string $result
- *      Current result string that will be checked.
- * 
- * @return string
- *      Resulting string with or without an additional space.
+ * @param $result
+ *   Current result string that will be checked.
+ * @return
+ *   Resulting string with or without an additional space.
  */
 function coder_add_space(&$result) {
   if (substr($result, -1) == ')') {
@@ -708,21 +718,21 @@
  * removes the closing PHP tag and appends two empty lines.
  */
 function coder_trim_php($code) {
-  // Remove surrounding whitespace
+  // Remove surrounding whitespace.
   $code = trim($code);
   
-  // Insert CVS keyword Id
+  // Insert CVS keyword Id.
   // Search in the very first 1000 chars, insert only one instance.
   if (strpos(substr($code, 0, 1000), '$Id') === false) {
     $code = preg_replace('/<\?php\n/', "<?php\n// \$Id\$\n\n", $code, 1);
   }
   
-  // Remove closing PHP tag
+  // Remove closing PHP tag/
   if (substr($code, -2) == '?>') {
     $code = rtrim($code, '?>');
   }
   
-  // Append two empty lines
+  // Append two empty lines/
   $code .= str_repeat(chr(10), 2);
   
   return $code;
@@ -754,7 +764,7 @@
  * @param string $prefix
  *      Prefix of the functions to execute.
  *
- * @return string
+ * @return
  *      The processed source code.
  */
 function coder_exec_processors($code, $prefix = '') {
@@ -799,6 +809,8 @@
 
 /**
  * Orders preprocessors by weight.
+ * @note
+ *   Callback function for uasort()
  */
 function coder_order_processors($a, $b) {
   if (isset($a['#weight']) && isset($b['#weight'])) {
@@ -832,14 +844,14 @@
 }
 
 function coder_preprocessor_ml_array_add_comma() {
-  // @bug coder.module:1010
+  // @bug coder.module:1010.
   return array(
     '#title' => 'Append a comma to the last value of multiline arrays.',
-    // ^[\040\t]*(?!\*|\/\/)[^\*\/\n]*? matches anything in front of array, but not comments
-    // \sarray\( prevents matching of in_array() and function calls
-    // (\n|(?X>!\);).+?,?\n) matches a line break or the first array item
-    // (.*?[^,;]) matches the rest array items
-    // ,?(\n\s*)\); matches the end of multiline array, optionally including a comma
+    // ^[\040\t]*(?!\*|\/\/)[^\*\/\n]*? matches anything in front of array, but not comments.
+    // \sarray\( prevents matching of in_array() and function calls.
+    // (\n|(?X>!\);).+?,?\n) matches a line break or the first array item.
+    // (.*?[^,;]) matches the rest array items.
+    // ,?(\n\s*)\); matches the end of multiline array, optionally including a comma.
     '#search' => '/(^[\040\t]*(?!\*|\/\/)[^\*\/\n]*?\sarray\()(\n|(?>!\);).+?,?\n)(.*?[^,;]),?(\n\s*\);)/ism',
     '#replace' => '$1$2$3,$4',
     #'#debug' => true,
@@ -850,12 +862,12 @@
   return array(
     '#title' => 'Move inline comments above remarked line.',
     '#weight' => 2,
-    // [\040\t] matches only a space or tab
-    // (?!case) prevents matching of case statements
-    // \S prevents matching of lines containing only a comment
-    // [^:] prevents matching of URL protocols
-    // [^;\$] prevents matching of CVS keyword Id comment and double slashes
-    //   in quotes (f.e. "W3C//DTD")
+    // [\040\t] matches only a space or tab.
+    // (?!case) prevents matching of case statements.
+    // \S prevents matching of lines containing only a comment.
+    // [^:] prevents matching of URL protocols.
+    // [^;\$] prevents matching of CVS keyword Id comment and double slashes.
+    //   in quotes (f.e. "W3C//DTD").
     '#search' => '@^([\040\t]*)(?!case)(\S.+?)[\040\t]*[^:]//\s*([^;\$]+?)$@m',
     '#replace' => "$1// $3\n$1$2",
   );
@@ -894,22 +906,22 @@
 }
 
 function coder_postprocessor_multiple_vars() {
-  // @todo Prevent matching of multiple lines separated by a blank line 26/03/2007 sun
+  // @todo Prevent matching of multiple lines separated by a blank line 26/03/2007 sun.
   return array(
     '#title' => 'Align equal signs of multiple variable assignments in the same column.',
-    // \s* matches whitespace including new lines
-    // \$.+? matches variable names
-    // {3,} requires the pattern to match at least 3 times
+    // \s* matches whitespace including new lines.
+    // \$.+? matches variable names.
+    // {3,} requires the pattern to match at least 3 times.
     '#search' => '/^(\s*\$.+? = .+?$){3,}/m',
     '#replace_callback' => 'coder_replace_multiple_vars',
   );
 }
 
 function coder_replace_multiple_vars($matches) {
-  // Retrieve all variable name = variable value pairs
+  // Retrieve all variable name = variable value pairs.
   preg_match_all('/^(\s*)(\$.+?) (.?)= (.+?$)/m', $matches[0], $vars, PREG_SET_ORDER);
   
-  // Determine the longest variable name
+  // Determine the longest variable name.
   $maxlength = 0;
   foreach ($vars as $var) {
     if (strlen($var[2]) > $maxlength) {
@@ -917,7 +929,7 @@
     }
   }
   
-  // Realign variable values at the longest variable names
+  // Realign variable values at the longest variable names.
   $return = '';
   $extra_spaces = 0;
   for ($c = 0, $cc = count($vars); $c < $cc; ++$c) {
@@ -928,7 +940,7 @@
     $return .= str_repeat(' ', $extra_spaces) .' '. $vars[$c][3] .'= ';
     $return .= $vars[$c][4];
     if ($c < $cc - 1) {
-      // Append a line break, but not to the last variable assignment
+      // Append a line break, but not to the last variable assignment.
       $return .= "\n";
     }
   }
@@ -937,33 +949,33 @@
 }
 
 function coder_postprocessor_array_rearrange() {
-  // @bug common.inc, comment.module
-  // not yet working properly 25/03/2007 sun
+  // @bug common.inc, comment.module:
+  // Not yet working properly 25/03/2007 sun.
   return array(
     '#title' => 'Break array elements into separate lines, indented one level.',
-    // ([\040\t]*) matches blanks and tabs
-    // (.*?array\() matches anything and 'array('
-    // ((.+ => .+, ){3,}) matches all array items, except the last one
-    // (.+ => ([^\(\)]+)) matches the last array item, excluding
-    //   arrays or functions (starting with a left parenthesis) [not supported yet]
+    // ([\040\t]*) matches blanks and tabs.
+    // (.*?array\() matches anything and 'array('.
+    // ((.+ => .+, ){3,}) matches all array items, except the last one.
+    // (.+ => ([^\(\)]+)) matches the last array item, excluding.
+    //   arrays or functions (starting with a left parenthesis) (not supported yet).
     '#search' => '/^([\040\t]*)(.*?array\()((.+ => .+, ){3,})(.+ => ([^\(\)]+))\)/m',
     '#replace_callback' => 'coder_replace_array_rearrange',
   );
 }
 
 function coder_replace_array_rearrange($matches) {
-  // Retrieve all array items, except the last one
+  // Retrieve all array items, except the last one.
   preg_match_all('/(.+? => .+?,) /', $matches[3], $items);
   
-  // The original line including array(
+  // The original line including array(.
   $return = $matches[1] . $matches[2] ."\n";
   foreach ($items[1] as $item) {
-    // All array items, except the last one, with extra indent
+    // All array items, except the last one, with extra indent.
     $return .= $matches[1] .'  '. $item ."\n";
   }
-  // Last array item, with extra indent and comma
+  // Last array item, with extra indent and comma.
   $return .= $matches[1] .'  '. $matches[5] .",\n";
-  // Closing parenthesis (on a new line)
+  // Closing parenthesis (on a new line).
   $return .= $matches[1] .')';
   
   return $return;
Index: scripts/coder_format/coder_format.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/scripts/coder_format/coder_format.php,v
retrieving revision 1.2
diff -u -r1.2 coder_format.php
--- scripts/coder_format/coder_format.php	7 Apr 2007 16:08:33 -0000	1.2
+++ scripts/coder_format/coder_format.php	8 Jan 2008 01:54:08 -0000
@@ -3,6 +3,7 @@
 
 /**
  * @file
+ * 
  * Coder format shell invocation script.
  * 
  * @param string $sourcefile
@@ -46,7 +47,7 @@
 require_once realpath(dirname($_SERVER['PHP_SELF'])) .'/coder_format.inc';
 
 if (!empty($_SERVER['argv'])) {
-  // Remove self-reference
+  // Remove self-reference.
   array_shift($_SERVER['argv']);
   
   $undo     = false;
@@ -78,7 +79,7 @@
     exit;
   }
   
-  // Process a single file
+  // Process a single file.
   $sourcefile = array_shift($_SERVER['argv']);
   $targetfile = array_shift($_SERVER['argv']);
   
Index: tests/coder_6x.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/tests/coder_6x.inc,v
retrieving revision 1.5.2.17
diff -u -r1.5.2.17 coder_6x.inc
--- tests/coder_6x.inc	11 Dec 2007 15:37:17 -0000	1.5.2.17
+++ tests/coder_6x.inc	8 Jan 2008 01:53:46 -0000
@@ -1,75 +1,84 @@
 <?php
 // $Id: coder_6x.inc,v 1.5.2.17 2007/12/11 15:37:17 snpower Exp $
 
+/**
+ * @file
+ * 
+ * This file implements tests for Drupal 6.x
+ *
+ * It is never actually called by the coder code, but is read when running
+ * admin/coder/coder
+ */
+
 function this_is_not_a_menu_hook() {
   $items = array();
-  $items[] = array(); // this should not generate an error
+  $items[] = array(); // This should not generate an error.
   return $items;
 }
 
 function _coder_6x_l_tests() {
   $link = l(t($display_vars['back_to_top']), 'faq', array('fragment' => '')); // this is ok
   $link = l(t($display_vars['back_to_top']), 'faq', NULL, NULL); // this is not ok
-  $output = l($image, $item['filepath'], $link_attributes, NULL, NULL, FALSE, TRUE); // not ok
+  $output = l($image, $item['filepath'], $link_attributes, NULL, NULL, FALSE, TRUE); // Not ok.
 }
 
 function _coder_6x_more_tests() {
-  if (taxonomy_node_get_terms($nid)) { // should generate an error
+  if (taxonomy_node_get_terms($nid)) { // Should generate an error.
   }
-  if (taxonomy_node_get_terms($node->nid)) { // should generate an error
+  if (taxonomy_node_get_terms($node->nid)) { // Should generate an error.
   }
-  if (taxonomy_node_get_terms($node)) { // not an error
+  if (taxonomy_node_get_terms($node)) { // Not an error.
   }
   $output = strtr(format_plural($num, 'There is currently 1 %type post on your site.', 'There are currently @count %type posts on your site.'), array('%type' => theme('placeholder', $type))); // a valid error
   $output = notstrtr(format_plural($num, 'There is currently 1 %type post on your site.', 'There are currently @count %type posts on your site.'), array('%type' => theme('placeholder', $type))); // not an error
 
-  watchdog('user', t('Removed %username user.', array('%username' => $user->name))); // an error
-  watchdog('user', 'Removed %username user.', array('%username' => $user->name)); // not an error
-  watchdog('debug', 'My debug message here'); // not ok
-
-  $complex = unserialize(cache_get('complex_cid')); // an error
-  cache_set('simple_cid', 'cache', $simple); // an error
-  $ip = $_SERVER['REMOTE_ADDR']; // an error
+  watchdog('user', t('Removed %username user.', array('%username' => $user->name))); // An error.
+  watchdog('user', 'Removed %username user.', array('%username' => $user->name)); // Not an error.
+  watchdog('debug', 'My debug message here'); // Not ok.
+
+  $complex = unserialize(cache_get('complex_cid')); // An error.
+  cache_set('simple_cid', 'cache', $simple); // An error.
+  $ip = $_SERVER['REMOTE_ADDR']; // An error.
 
-  if ($file = file_check_upload('picture_upload')) { // an error
-    $file = file_save_upload('picture_upload', $destination, FILE_EXISTS_REPLACE); // an error
+  if ($file = file_check_upload('picture_upload')) { // An error.
+    $file = file_save_upload('picture_upload', $destination, FILE_EXISTS_REPLACE); // An error.
   }
 
-  if ($file = file_save_upload('picture_upload', $validators)) { // ok
+  if ($file = file_save_upload('picture_upload', $validators)) { // Ok.
   }
 
-  $sql = 'UPDATE {file_revisions} SET vid=1'; // an error
-  if (db_query('SELECT * FROM {file_revisions}')) { // an error
+  $sql = 'UPDATE {file_revisions} SET vid=1'; // An error.
+  if (db_query('SELECT * FROM {file_revisions}')) { // An error.
   } 
 
-  // add FAPI tests
+  // Add FAPI tests.
   $form = array(
-    '#base' => 'my_shared_form_id', // error
-    '#pre_render' => '<div>', // error
+    '#base' => 'my_shared_form_id', // An error.
+    '#pre_render' => '<div>', // An error.
   );
   $form['#base'] = 'http://example.com';
-  $form['#submit']['my_submit_function'] = array($param1, $param2); // error
-  $form['#submit']['my_validate_function'] = array(); // error
+  $form['#submit']['my_submit_function'] = array($param1, $param2); // An error.
+  $form['#submit']['my_validate_function'] = array(); // An error.
   $form['#multistep'] = TRUE;
   $form['#DANGEROUS_SKIP_CHECK'] = TRUE;
 
-  drupal_retrieve_form('testform'); // missing second arg
-  drupal_retrieve_form($form_id, $form_state); // ok
+  drupal_retrieve_form('testform'); // Missing second arg.
+  drupal_retrieve_form($form_id, $form_state); // Ok.
 
-  form_set_value($element, 'value', $form_status); // This one is okay
-  form_set_value($element, 'value'); // error
+  form_set_value($element, 'value', $form_status); // Ok.
+  form_set_value($element, 'value'); // An error.
 
-  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", t("Don't do it unless you're really sure!"), t('Delete it'), t('Go back'), 'delete'); // should fail
+  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", t("Don't do it unless you're really sure!"), t('Delete it'), t('Go back'), 'delete'); // Should fail.
 
-  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", $options); // is ok
-  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", array()); // also ok
+  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", $options); // Ok.
+  confirm_form($form, t('Do you really want to delete this?'), "node/$nid", array()); // Ok.
 
-  custom_url_rewrite($url); // not ok
-  custom_url_rewrite_inbound($url); // ok
+  custom_url_rewrite($url); // An error.
+  custom_url_rewrite_inbound($url); // Ok.
 
-  $form_location = variable_get('comment_form_location', COMMENT_FORM_SEPARATE_PAGE); // not ok
-  $form_location = variable_get('comment_form_location_page', COMMENT_FORM_SEPARATE_PAGE); // ok
-  $variable_name = 'comment_form_location'.'_abc'; // ok
+  $form_location = variable_get('comment_form_location', COMMENT_FORM_SEPARATE_PAGE); // An error.
+  $form_location = variable_get('comment_form_location_page', COMMENT_FORM_SEPARATE_PAGE); // Ok.
+  $variable_name = 'comment_form_location'.'_abc'; // Ok.
 
   $log_path = 'admin/logs/';
 
@@ -85,76 +94,76 @@
   taxonomy_get_vocabulary($vid);
 
   db_result($result, $row);
-  db_result($result); // ok
-  $number = db_result(db_query("SELECT COUNT(*) FROM {flood} WHERE event = '%s' AND hostname = '%s' AND timestamp > %d", $name, ip_address(), time() - 3600)); //ok
+  db_result($result); // Ok.
+  $number = db_result(db_query("SELECT COUNT(*) FROM {flood} WHERE event = '%s' AND hostname = '%s' AND timestamp > %d", $name, ip_address(), time() - 3600)); // Ok.
 
 
-  // book api tests
-  book_admin_orphan(); // deprecated
-  book_content(); // deprecated
-  book_form(); // deprecated
-  book_insert(); // deprecated
-  book_location(); // deprecated
-  book_location_down(); // deprecated
-  book_node_visitor_html_post(); // deprecated
-  book_node_visitor_html_pre(); // deprecated
-  book_recurse(); // deprecated
-  book_toc_recurse(); // deprecated
-  book_tree(); // deprecated
-  book_tree_recurse(); // deprecated
-
-  book_admin_edit($nid); // not ok
-  book_admin_edit($form_state, $node); // ok
-
-  book_toc(); // not ok
-  book_toc($exclude); // not ok
-  book_toc($bid, array(), $depth); // ok
-
-  book_export_html($nid, $depth); // not ok
-  book_export_html($nid); // ok
-
-  book_export(); // not ok
-  book_export($type); // not ok
-  book_export($type, $nid); // ok
-
-  book_outline($nid); // not ok
-  book_outline($node->nid); // not ok
-  book_outline($node); // ok
-
-  book_prev($node); // not ok
-  book_prev($book_link); // ok
-  book_next($node); // not ok
-  book_next($book_link); // ok
-  // end book api tests
-
-  drupal_mail($action, $to, $subject, $body, $from); // not ok
-  drupal_mail('action_email', $recipient, $subject, $body, $from); // not ok
-  drupal_mail('action_email', $account->mail, $subject, $body, $from); // not ok
-  drupal_mail('action_email', 'foo@foo.com', $subject, $body, $from); // not ok
-  drupal_mail('system', 'action_email', $recipient, $language, $params); // ok
+  // Book api tests.
+  book_admin_orphan(); // Deprecated.
+  book_content(); // Deprecated.
+  book_form(); // Deprecated.
+  book_insert(); // Deprecated.
+  book_location(); // Deprecated.
+  book_location_down(); // Deprecated.
+  book_node_visitor_html_post(); // Deprecated.
+  book_node_visitor_html_pre(); // Deprecated.
+  book_recurse(); // Deprecated.
+  book_toc_recurse(); // Deprecated.
+  book_tree(); // Deprecated.
+  book_tree_recurse(); // Deprecated.
+
+  book_admin_edit($nid); // Not ok.
+  book_admin_edit($form_state, $node); // Ok.
+
+  book_toc(); // Not ok.
+  book_toc($exclude); // Not ok.
+  book_toc($bid, array(), $depth); // Ok.
+
+  book_export_html($nid, $depth); // Not ok.
+  book_export_html($nid); // Ok.
+
+  book_export(); // Not ok.
+  book_export($type); // Not ok.
+  book_export($type, $nid); // Ok.
+
+  book_outline($nid); // Not ok.
+  book_outline($node->nid); // Not ok.
+  book_outline($node); // Ok.
+
+  book_prev($node); // Not ok.
+  book_prev($book_link); // Ok.
+  book_next($node); // Not ok.
+  book_next($book_link); // Ok.
+  // End book api tests.
+
+  drupal_mail($action, $to, $subject, $body, $from); // Not ok.
+  drupal_mail('action_email', $recipient, $subject, $body, $from); // Not ok.
+  drupal_mail('action_email', $account->mail, $subject, $body, $from); // Not ok.
+  drupal_mail('action_email', 'foo@foo.com', $subject, $body, $from); // Not ok.
+  drupal_mail('system', 'action_email', $recipient, $language, $params); // Ok.
   
 }
 
-function _coder_6x_test_link_alter($node, &$links) { // an error
+function _coder_6x_test_link_alter($node, &$links) { // An error.
 }
 
-function _coder_6x_test2_link_alter(&$links, $node) { // not an error
+function _coder_6x_test2_link_alter(&$links, $node) { // Not an error.
 }
 
-function _coder_6x_test_mail_alter(&$mailkey, &$to, &$subject, &$body, &$from, &$headers) { // this is an error
+function _coder_6x_test_mail_alter(&$mailkey, &$to, &$subject, &$body, &$from, &$headers) { // An error.
 }
 
-function _coder_6x_test2_mail_alter(&$message) { // not an error
+function _coder_6x_test2_mail_alter(&$message) { // An error.
 }
 
 function coder_node_get_name() {
   node_get_name('name');
 }
 
-function myform_validate($form_id, $form) { // this will fail.
+function myform_validate($form_id, $form) { // This will fail.
 }
 
-function myform_submit($form_id, $form) { //this willfail
+function myform_submit($form_id, $form) { // This will fail.
   $form['#submit']['newsubmit'] = array();
   $form['#submit'][] = "newsubmit";
 }
@@ -165,16 +174,16 @@
 function mymodule_auth($username, $password, $server) {
 }
 
-function mymodule_help($section) { // not ok
+function mymodule_help($section) { // Not ok.
 }
 
-function mymodule_help($section, $arg) { // ok
+function mymodule_help($section, $arg) { // Ok.
 }
 
 function mymodule_enable() {
-  node_access_rebuild(); // not ok in node access modules
+  node_access_rebuild(); // Not ok in node access modules.
 }
 
 function mymodule_disable() {
-  node_access_rebuild(); // not ok in node access modules
+  node_access_rebuild(); // Not ok in node access modules.
 }
Index: tests/coder_comment.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/tests/coder_comment.inc,v
retrieving revision 1.1.4.1
diff -u -r1.1.4.1 coder_comment.inc
--- tests/coder_comment.inc	21 Nov 2007 10:41:04 -0000	1.1.4.1
+++ tests/coder_comment.inc	8 Jan 2008 01:53:43 -0000
@@ -1,7 +1,9 @@
 <?php
-/** @file
-* This is a comment error
- *This is a comment error
+/** 
+ * @file
+ * 
+* This is a comment error.
+ *This is a comment error.
  */
 
 /*
Index: tests/coder_sql.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/tests/Attic/coder_sql.inc,v
retrieving revision 1.1.4.4
diff -u -r1.1.4.4 coder_sql.inc
--- tests/coder_sql.inc	15 Sep 2007 12:01:04 -0000	1.1.4.4
+++ tests/coder_sql.inc	8 Jan 2008 01:46:34 -0000
@@ -1,11 +1,14 @@
 <?php
 // $Id: coder_sql.inc,v 1.1.4.4 2007/09/15 12:01:04 douggreen Exp $
 
-/** @file
- * This include file implements tests for the Drupal SQL
+/**
+ * @file
+ * 
+ * This include file implements tests for the Drupal SQL as defined by
+ * http://drupal.org/node/2497
  *
  * It is never actually called by the coder code, but is read when running
- * admin/coder/coder
+ * admin/coder/coder.
  */
 
 function coder_test_sql() {
Index: tests/coder_style.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/coder/tests/coder_style.inc,v
retrieving revision 1.6.2.2
diff -u -r1.6.2.2 coder_style.inc
--- tests/coder_style.inc	13 Dec 2007 01:15:43 -0000	1.6.2.2
+++ tests/coder_style.inc	8 Jan 2008 01:47:50 -0000
@@ -1,33 +1,36 @@
 <?php
 // $Id: coder_style.inc,v 1.6.2.2 2007/12/13 01:15:43 douggreen Exp $
 
-/** @file
- * This include file implements tests for the Drupal Standards
+/**
+ * @file
+ * 
+ * This include file implements tests for the Drupal Standards as defined
+ * at http://drupal.org/coding-standards
  *
  * It is never actually called by the coder code, but is read when running
- * admin/coder/coder
+ * admin/coder/coder.
  */
 
 function coder_test_tab() {
-  // tab in	comment - is this ok?
-  $var = 'tab in	quote'; // is this ok?
+  // Tab in	comment - is this ok?
+  $var = 'tab in	quote'; // Is this ok?
 	$var = 'tab error';
 }
 
 function coder_test_stdclass() {
-  $var = new stdClass(); // this is ok
-  $var = new StdClass(); // this is not
-  $var = new stdclassToo(); // should be camelcase rule
+  $var = new stdClass(); // This is ok.
+  $var = new StdClass(); // This is not.
+  $var = new stdclassToo(); // Should be camelcase rule.
 }
 
 function coderCamelCase() {
-  $camelCaseVar = 'whatever'; // camel case functions and vars not allowed
-  $var = $obj->camelCase; // but camel case objects elements are
-  new camcelCase(); // is ok
+  $camelCaseVar = 'whatever'; // Camel case functions and vars not allowed.
+  $var = $obj->camelCase; // But camel case objects elements are.
+  new camcelCase(); // Is ok.
 }
 
 function coder_test_two_errors_on_same_line() {
-  if('test=' . $test == 'test='){ // there are 3 errors on this line
+  if('test=' . $test == 'test='){ // There are 3 errors on this line.
   }
 }
 
@@ -38,10 +41,10 @@
 }
 
 function coder_hex_number() {
-  $var = 0xFF; // should NOT be camelcase
+  $var = 0xFF; // Should NOT be camelcase.
 }
 
-function coder_multiline_quote() { // from Drupal5 block.module
+function coder_multiline_quote() { // From Drupal5 block.module.
   return t('<p>Blocks are boxes of content that may be rendered into certain regions of your web pages, for example, into sidebars. They are usually generated automatically by modules, but administrators can create blocks manually.</p>
 <p>Only enabled blocks are shown. You can position blocks by specifying which area of the page they should appear in (e.g., a sidebar).  Highlighted labels on this page show the regions into which blocks can be rendered. You can specify where within a region a block will appear by adjusting its weight.</p>
 <p>If you want certain blocks to disable themselves temporarily during high server loads, check the "Throttle" box. You can configure the auto-throttle on the <a href="@throttle">throttle configuration page</a> after having enabled the throttle module.</p>
@@ -49,8 +52,8 @@
 }
 
 function coder_break() {
-  print '<br>'; // should generate an error, and will throw performance warning
-  ?><br><?php // should also generate an error
+  print '<br>'; // Should generate an error, and will throw performance warning.
+  ?><br><?php // Should also generate an error.
 }
 
 function coder_heredoc() {
@@ -64,13 +67,13 @@
 }
 
 function coder_dot() {
-  if ($file = file_check_upload($fieldname . '_upload')) { // not ok
+  if ($file = file_check_upload($fieldname . '_upload')) { // Not ok.
   }
-  $v .= 'bugger'; // ok
-  $a = $v .'bugger'; // ok
-  $a = $v ."bugger"; // ok, but will throw performance warning
-  $a = $v.'bugger'; // not ok
-  $a = $some_func().'bugger'; // not ok
+  $v .= 'bugger'; // Ok.
+  $a = $v .'bugger'; // Ok.
+  $a = $v ."bugger"; // Ok, but will throw performance warning.
+  $a = $v.'bugger'; // Not ok.
+  $a = $some_func().'bugger'; // Not ok.
 }
 
 function coder_array_indexes() {
@@ -78,5 +81,5 @@
   $a['hello'] = 'this is no';
 }
 
-// should generate an error about the trailing php close
+// Should generate an error about the trailing php close.
 ?>
