[pLog-svn] r1626 - in plog/trunk/class: . mail mail/phpmailer

[oscar at devel.plogworld.net]

Author: oscar
Date: 2005-03-29 07:54:45 +0000 (Tue, 29 Mar 2005)
New Revision: 1626

Modified:
   plog/trunk/class/Doxyfile
   plog/trunk/class/mail/emailmessage.class.php
   plog/trunk/class/mail/emailservice.class.php
   plog/trunk/class/mail/phpmailer/class.phpmailer.php
   plog/trunk/class/mail/phpmailer/class.smtp.php
Log:
some more documentation added 


Modified: plog/trunk/class/Doxyfile
===================================================================
--- plog/trunk/class/Doxyfile	2005-03-28 17:24:37 UTC (rev 1625)
+++ plog/trunk/class/Doxyfile	2005-03-29 07:54:45 UTC (rev 1626)
@@ -416,7 +416,7 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/
+INPUT                  = object/ dao/ logger/ gallery/ locale/ config/ file/ database/ data/forms security/ xml/ controller/ mail/
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

Modified: plog/trunk/class/mail/emailmessage.class.php
===================================================================
--- plog/trunk/class/mail/emailmessage.class.php	2005-03-28 17:24:37 UTC (rev 1625)
+++ plog/trunk/class/mail/emailmessage.class.php	2005-03-29 07:54:45 UTC (rev 1626)
@@ -1,16 +1,14 @@
 <?php
 
-    /**
-     * @package mail
-     */
-
-
 	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
 
     define( "MAX_LINE_LENGTH", 998 );
 
 	/**
-     * Represents an email message.
+	 * \ingroup Mail
+	 * 
+     * Represents an email message and has basic setter and getter methods for all the most
+     * basic attributes of an email message (To:, From:, Bcc:, etc)
      */
     class EmailMessage extends Object 
     {

Modified: plog/trunk/class/mail/emailservice.class.php
===================================================================
--- plog/trunk/class/mail/emailservice.class.php	2005-03-28 17:24:37 UTC (rev 1625)
+++ plog/trunk/class/mail/emailservice.class.php	2005-03-29 07:54:45 UTC (rev 1626)
@@ -1,22 +1,67 @@
 <?php
 
-    /**
-     * @package mail
-     */
+	/**
+	 * \defgroup Mail
+	 *
+	 * Module that allows to easily send email messages from within pLog. The actual email sending
+	 * is carried out via the PHPMailer package (http://phpmailer.sourceforge.net/) and the classes of
+	 * this module are just commodity wrappers around PHPMailer.
+	 * 
+	 * The EmailMessage class is an abstract representation of an email message, while the EmailService
+	 * class takes care of sending out the messages.	
+	 */
 
-
 	include_once( PLOG_CLASS_PATH."class/object/object.class.php" );
     include_once( PLOG_CLASS_PATH."class/config/config.class.php" );
     include_once( PLOG_CLASS_PATH."class/mail/emailmessage.class.php" );
     include_once( PLOG_CLASS_PATH."class/mail/phpmailer/class.phpmailer.php" );
 
     /**
+     * \ingroup Mail
+     *
      * Provides services to send emails via PHPs built-in smtp capabilities.
      *
      * This service can be enabled or disabled by using the "email_service_enabled" from
      * the configuration file. It also requires PHP to be built with the smtp handling
      * libraries and those must be enabled.
-     */
+     *
+	 * An example of how to send an email message is as follows:
+	 *
+	 * <pre>
+	 *  $message = new EmailMessage();
+	 *  $message->addTo( "address1 at domain.com" );
+	 *  $message->addFrom( "myself at myself.com" );
+	 *  $message->setSubject( "This is a sample message" );
+	 *  $message->setBody( "this is the body of the message" );
+	 *  $service = new EmailService();
+	 *  if( $service->sendMessage( $message ))
+	 *    print( "message sent ok!" );
+	 *  else
+	 *    print( "error sending message" );
+	 * </pre>
+	 *
+	 * The EmailService class hides all the details about how the message is sent, the mechanism, etc.
+	 * It wil in fact use certain configuration parameters such as:
+	 *
+	 * - email_service_enabled to determine whether emails should be sent at all.
+	 * - email_service_type can be one of these four values:
+	 *   # php (requires PHP's mail() function)
+	 *   # smtp (see below)
+	 *   # qmail
+	 *   # sendmail
+	 *
+	 * If email_service_type is set as <b>smtp</b>, the following settings are also required:
+	 *
+	 * - smtp_host name of the host used for sending the messages
+	 * - smtp_port port where the SMTP is listening, 25 by default
+	 * - smtp_use_authentication Wether we should perform some basic authentication agains the host
+	 * 
+	 * If smtp_use_authentication is set to yes, the following settings will determine the right 
+	 * username and password to use:
+	 *	 
+	 * - smtp_username
+	 * - smtp_password
+	 */
     class EmailService extends Object 
     {
 

Modified: plog/trunk/class/mail/phpmailer/class.phpmailer.php
===================================================================
--- plog/trunk/class/mail/phpmailer/class.phpmailer.php	2005-03-28 17:24:37 UTC (rev 1625)
+++ plog/trunk/class/mail/phpmailer/class.phpmailer.php	2005-03-29 07:54:45 UTC (rev 1626)
@@ -16,6 +16,7 @@
  * @package PHPMailer
  * @author Brent R. Matzelle
  * @copyright 2001 - 2003 Brent R. Matzelle
+ * \ingroup Mail
  */
 class PHPMailer
 {

Modified: plog/trunk/class/mail/phpmailer/class.smtp.php
===================================================================
--- plog/trunk/class/mail/phpmailer/class.smtp.php	2005-03-28 17:24:37 UTC (rev 1625)
+++ plog/trunk/class/mail/phpmailer/class.smtp.php	2005-03-29 07:54:45 UTC (rev 1626)
@@ -20,6 +20,7 @@
  * to an SMTP server.
  * @package PHPMailer
  * @author Chris Ryan
+ * \ingroup Mail
  */
 class SMTP
 {