updated devel

sites/all/modules/contrib/dev/devel/devel.mail.inc

@@ -1,4 +1,5 @@
 <?php
+
 /**
  * @file
  * MailSystemInterface for logging mails to the filesystem.
@@ -16,8 +17,20 @@
  *
  */
 
+/**
+ * Logs mail messages to the filesystem.
+ */
 class DevelMailLog extends DefaultMailSystem {
 
+  /**
+   * Converts a message array to a string.
+   *
+   * @param $message
+   *   The message array containing the body and headers.
+   *
+   * @return
+   *   The message as it will be printed in the file.
+   */
   public function composeMessage($message) {
     $mimeheaders = array();
     $message['headers']['To'] = $message['to'];
@@ -35,6 +48,15 @@ class DevelMailLog extends DefaultMailSystem {
     return $output;
   }
 
+  /**
+   * Gets a filename for a message using tokens.
+   *
+   * @param $message
+   *   The message that will supply values for token replacement.
+   *
+   * @return
+   *   The full path and filename after token replacement.
+   */
   public function getFileName($message) {
     $output_directory = $this->getOutputDirectory();
     $this->makeOutputDirectory($output_directory);
@@ -48,19 +70,26 @@ class DevelMailLog extends DefaultMailSystem {
     return $output_directory . '/' . $this->dirify(str_replace(array_keys($tokens), array_values($tokens), $output_file_format));
   }
 
+  /**
+   * Convert a string to a valid directory name.
+   *
+   * @return
+   *   The sanitized string, replacing any characters not whitelisted with "_".
+   */
   private function dirify($string) {
     return preg_replace('/[^a-zA-Z0-9_\-\.@]/', '_', $string);
   }
+
   /**
-   * Save an e-mail message to a file, using Drupal variables and default settings.
-   *
-   * @see http://php.net/manual/en/function.mail.php
-   * @see drupal_mail()
+   * Save a mail message to a file using Drupal variables and default settings.
    *
    * @param $message
    *   A message array, as described in hook_mail_alter().
    * @return
    *   TRUE if the mail was successfully accepted, otherwise FALSE.
+   *
+   * @see http://php.net/manual/en/function.mail.php
+   * @see drupal_mail()
    */
   public function mail(array $message) {
     $output = $this->composeMessage($message);
@@ -69,14 +98,25 @@ class DevelMailLog extends DefaultMailSystem {
     return file_put_contents($output_file, $output);
   }
 
+  /**
+   * Creates the directory to contain the message file if necessary.
+   *
+   * @throws Exception
+   *   Exception thrown when unable to create the destination directory.
+   */
   protected function makeOutputDirectory($output_directory) {
     if (!file_prepare_directory($output_directory, FILE_CREATE_DIRECTORY)) {
       throw new Exception("Unable to continue sending mail, $output_directory is not writable");
     }
   }
 
+  /**
+   * Retrieves the directory that contains message files.
+   *
+   * @return
+   *   The path to mail messages, possibly using a file URI scheme.
+   */
   public function getOutputDirectory() {
     return variable_get('devel_debug_mail_directory', 'temporary://devel-mails');
   }
 }
-?>