? mimemail.module.documentation.patch
Index: mimemail.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/mimemail/mimemail.module,v
retrieving revision 1.14.2.7
diff -u -p -r1.14.2.7 mimemail.module
--- mimemail.module	1 Mar 2008 05:12:30 -0000	1.14.2.7
+++ mimemail.module	16 Apr 2008 20:12:31 -0000
@@ -1,8 +1,8 @@
-<?php /* $Id: mimemail.module,v 1.14.2.7 2008/03/01 05:12:30 vauxia Exp $ */
+<?php /* $Id: mimemail.module,v 1.24 2008/03/01 05:11:52 vauxia Exp $ */
 
 /**
- * @file Component module for sending Mime-encoded emails
- * 
+ * @file
+ * Component module for sending MIME-encoded e-mails.
  */
  
 /**
@@ -27,6 +27,12 @@ function mimemail_menu() {
   return $items;
 }
 
+/**
+ * Administration settings.
+ *
+ * @return
+ *   The administration from.
+ */
 function mimemail_settings() {
 
   // override the smtp_library value if mimemail is chosen to handle all mail
@@ -150,16 +156,42 @@ function mimemail_user($op, &$edit, &$us
 }
 
 /**
- * Send a mime-encoded email
- * 
- * @param $sender The email address or user object
- * @param $recipient An email address or user object * @param $subject An subject line string
- * @param $body An HTML body
- * @param $plaintext Whether to send message as plaintext only
- * @param $headers Optional e-mail headers in a keyed array
- * @param $text Optional plaintext portion of a multipart e-mail (instead of auto-generated)
- * 
- * @return result from mail() call
+ * Prepares a message for sending.
+ *
+ * This function sets the from address, if empty, determines whether the
+ * message should be plain text or not, and then MIME encodes the strings.
+ *
+ * @param $sender
+ *   The email address or user object who is sending the message.
+ * @param $recipient
+ *   An email address or user object who is receiving the message.
+ * @param $subject
+ *   A subject line string.
+ * @param $body
+ *   The message body in HTML format.
+ * @param $plaintext
+ *   Whether to send the message as plaintext only or HTML. If set to 1, Yes
+ *   or TRUE, then the message will be sent as plaintext.
+ * @param $headers
+ *   Optional e-mail headers in a keyed array.
+ * @param $text
+ *   Optional plaintext portion of a multipart e-mail (instead of auto-generated).
+ * @param $attachments
+ *   An array of arrays which describe one or more attachments. The internal
+ *   array consists of two parts: the file's path and the file's MIME type.
+ *   The array of arrays looks something like this:
+ *   Array
+ *   (
+ *     [0] => Array
+ *       (
+ *         [filepath] => '/path/to/file.name'
+ *         [filemime] => 'mime/type'
+ *       )
+ *   )
+ * @param $mailkey
+ *   An identifier for the message.
+ * @return
+ *   An array containing the MIME encoded message, including headers and body.
  */
 function mimemail_prepare($sender, $recipient, $subject, $body, $plaintext=null, $headers=array(), $text=null, $attachments=array(), $mailkey = '') {
 
@@ -203,6 +235,45 @@ function mimemail_prepare($sender, $reci
   return $message;
 }
 
+/**
+ * Sends a mime-encoded e-mail.
+ *
+ * This function first determines the mail engine to use, then prepares the
+ * message by calling the mail engine's prepare function, or
+ * mimemail_prepare() if another one does not exist, then sends the message.
+ *
+ * @param $sender
+ *   The email address or user object who is sending the message.
+ * @param $recipient
+ *   An email address or user object who is receiving the message.
+ * @param $subject
+ *   A subject line string.
+ * @param $body
+ *   The message body in HTML format.
+ * @param $plaintext
+ *   Whether to send the message as plaintext only or HTML. If set to 1, Yes
+ *   or TRUE, then the message will be sent as plaintext.
+ * @param $headers
+ *   Optional e-mail headers in a keyed array.
+ * @param $text
+ *   Optional plaintext portion of a multipart e-mail (instead of auto-generated).
+ * @param $attachments
+ *   An array of arrays which describe one or more attachments. The internal
+ *   array consists of two parts: the file's path and the file's MIME type.
+ *   The array of arrays looks something like this:
+ *   Array
+ *   (
+ *     [0] => Array
+ *       (
+ *         [filepath] => '/path/to/file.name'
+ *         [filemime] => 'mime/type'
+ *       )
+ *   )
+ * @param $mailkey
+ *   An identifier for the message.
+ * @return
+ *   An array containing the MIME encoded message, including headers and body.
+ */
 function mimemail($sender, $recipient, $subject, $body, $plaintext = NULL, $headers=array(), $text = NULL, $attachments = array(), $mailkey = '') {
 
   $engine = variable_get('mimemail_engine', 'mimemail') .'_mailengine';
@@ -225,9 +296,10 @@ function mimemail($sender, $recipient, $
 }
 
 /**
- * Returns available mailer engines.
+ * Retreives a list of all available mailer engines.
  *
- * @return an array of mailer engine names.
+ * @return
+ *   An array of mailer engine names.
  */
 function mimemail_get_engines() {
   $engines = array();
@@ -241,7 +313,14 @@ function mimemail_get_engines() {
 }
 
 /**
- * Default mailengine
+ * The default mailengine.
+ *
+ * @param $op
+ *   The operation to perform on the message.
+ * @param $message
+ *   The message to be sent.
+ * @return
+ *   Returns TRUE if the operation was successful or FALSE if it was not.
  */
 function mimemail_mailengine($op, $message = array()) {
   //default values
@@ -285,6 +364,24 @@ function mimemail_mailengine($op, $messa
   return false;
 }
 
+/**
+ * Overrides Drupal's default mail sending process.
+ *
+ * @param $mailkey
+ *   An identifier for the message.
+ * @param $to
+ *   An email address or user object who is receiving the message.
+ * @param $subject
+ *   A subject line string.
+ * @param $body
+ *   The message body in HTML format.
+ * @param $from
+ *   The email address or user object who is sending the message.
+ * @param $headers
+ *   Optional e-mail headers in a keyed array.
+ * @return
+ *   Returns the resultss of the call to mimemail().
+ */
 if (strpos(variable_get('smtp_library', ''), 'mimemail')
   && !function_exists('drupal_mail_wrapper')) {
 
@@ -293,6 +390,27 @@ if (strpos(variable_get('smtp_library', 
   }
 } 
 
+/**
+ * Modifys messages being sent through drupal_mail.
+ *
+ * Remove's unauthorized HTML from the body of a message being sent through
+ * drupal_mail() before it does it's final processing.
+ *
+ * @param $mailkey
+ *   An identifier for the message.
+ * @param $recipient
+ *   An email address or user object who is receiving the message.
+ * @param $subject
+ *   A subject line string.
+ * @param $body
+ *   The message body in HTML format.
+ * @param $sender
+ *   The email address or user object who is sending the message.
+ * @param $headers
+ *   Optional e-mail headers in a keyed array.
+ * @return
+ *   Returns the resultss of the call to mimemail().
+ */
 function mimemail_mail_alter($mailkey, &$recipient, &$subject, &$body, &$sender, &$headers) {
 
   if (!variable_get('mimemail_alter', 0)) return;
@@ -303,6 +421,15 @@ function mimemail_mail_alter($mailkey, &
   return;
 }
 
+/**
+ * Receive messages POSTed from an external source.
+ *
+ * This function enables messages to be sent via POST or some other RFC822
+ * source input (e.g. directly from a mail server).
+ *
+ * @return
+ *   The POSTed message.
+ */
 function mimemail_post() {
   $message = $_POST['message'];
   $token   = $_POST['token'];
@@ -315,6 +442,12 @@ function mimemail_post() {
   return mimemail_incoming($message);
 }
 
+/**
+ * Parses an externally received message.
+ *
+ * @param $message
+ *   The message to parse.
+ */
 function mimemail_incoming($message) {
   require_once dirname(__FILE__) .'/mimemail.inc';
   $mail = mimemail_parse($message);
@@ -327,11 +460,14 @@ function mimemail_incoming($message) {
 }
 
 /**
- * Formats an address string 
- * TODO could use some enhancement and stress testing 
- * 
- * @param $address - a user object, a text email address or an array containing name, mail
- * @return formatted address string
+ * Formats an address string.
+ *
+ * TODO could use some enhancement and stress testing.
+ *
+ * @param $address
+ *   A user object, a text email address or an array containing name, mail.
+ * @return
+ *   A formatted address string or FALSE.
  */
 function mimemail_address($address) {
   
@@ -379,7 +515,14 @@ function mimemail_address($address) {
 }
 
 /**
- * Themeable message body
+ * Themes the message body.
+ *
+ * @param $body
+ *   The message body to theme.
+ * @param $mailkey
+ *   An identifier for the message.
+ * @return
+ *   The themed HTML message body.
  */
 function theme_mimemail_message($body, $mailkey = null) {
   $output = '<html><head>';