Added jsdoc comment based documentation

helma/Mail.js

@@ -6,19 +6,43 @@
  * compliance with the License. A copy of the License is available at
  * http://adele.helma.org/download/helma/license.txt
  *
- * Copyright 1998-2006 Helma Software. All Rights Reserved.
+ * Copyright 1998-2007 Helma Software. All Rights Reserved.
  *
  * $RCSfile: Mail.js,v $
  * $Author: hannes $
- * $Revision: 1.3 $
+ * $Revision: 1.4 $
- * $Date: 2006/06/28 20:06:03 $
+ * $Date: 2006/11/27 12:47:04 $
  */
 
 
+/**
+ * Define the global namespace if not existing
+ */
 if (!global.helma) {
     global.helma = {};
 }
 
+/**
+ * Mail client enabling you to send e-mail via SMTP using Packages.javax.mail.
+ * <br /><br />
+ * A mail client object is created by using the helma.Mail() 
+ * constructor. The mail object then can be manipulated and sent 
+ * using the methods listed below.
+ * <br /><br />
+ * You will either need to set your mail server via the smtp
+ * property in the app.properties or server.properties file
+ * or pass the hostname of the mail server you want to use as a 
+ * parameter to the constructor.
+ * <br /><br />
+ * Note: Make sure that the SMTP server itself is well-configured, 
+ * so that it accepts e-mails coming from your server and does 
+ * not deny relaying. Best and fastest configuration is of course 
+ * if you run your own SMTP server (e.g. postfix) which might be 
+ * a bit tricky to set up, however.</p>
+ * 
+ * @param {String} smtp as String, the hostname of the mail server
+ * @constructor
+ */
 helma.Mail = function(smtp) {
     var OK          =  0;
     var SUBJECT     = 10;
@@ -98,8 +122,25 @@ helma.Mail = function(smtp) {
         return;
     };
 
+    /**
+     * The status of this Mail object.
+     */
     this.status = OK;
     
+    /**
+     * Sets the sender of an e-mail message.
+     * <br /><br />
+     * The first argument specifies the receipient's 
+     * e-mail address. The optional second argument 
+     * specifies the name of the recipient.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setFrom("tobi@helma.at", "Tobi Schaefer");</pre>
+     * 
+     * @param {String} addstr as String, sender email address
+     * @param {String} name as String, optional sender name
+     */
     this.setFrom = function(addstr, name) {
         try {
             if (addstr.indexOf("@") < 0) {
@@ -119,6 +160,15 @@ helma.Mail = function(smtp) {
         return;
     };
     
+    /**
+     * Sets the Reply-To address of an e-mail message.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setReplyTo("tobi@helma.at");</pre>
+     * 
+     * @param {String} addstr as String, the reply-to email address
+     */
     this.setReplyTo = function(addstr) {
         try {
             if (addstr.indexOf("@") < 0) {
@@ -133,6 +183,21 @@ helma.Mail = function(smtp) {
         return;
     }
 
+    /**
+     * Sets the recipient of an e-mail message.
+     * &nbsp;
+     * The first argument specifies the receipient's 
+     * e-mail address. The optional second argument 
+     * specifies the name of the recipient.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setTo("hop@helma.at");</pre>
+     * 
+     * @param {String} addstr as String, receipients email address
+     * @param {String} name as String, optional receipients name
+     * @see #addTo
+     */
     this.setTo = function(addstr, name) {
         try {
             addRecipient(addstr, name, Message.RecipientType.TO);
@@ -143,6 +208,23 @@ helma.Mail = function(smtp) {
         return;
     };
 
+    /**
+     * Adds a recipient to the address list of an e-mail message.
+     * <br /><br />
+     * The first argument specifies the receipient's 
+     * e-mail address. The optional second argument 
+     * specifies the name of the recipient.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setTo("hop@helma.at");
+     * mail.addTo("hopdoc@helma.at");
+     * mail.addTo("tobi@helma.at", "Tobi Schaefer");</pre>
+     * 
+     * @param {String} addstr as String, receipients email address
+     * @param {String} name as String, optional receipients name
+     * @see setTo
+     */
     this.addTo = function(addstr, name) {
         try {
             addRecipient(addstr, name, Message.RecipientType.TO);
@@ -163,6 +245,21 @@ helma.Mail = function(smtp) {
         return;
     }
 
+    /**
+     * Adds a recipient to the list of addresses to get a "blind carbon copy" of an e-mail message.
+     * <br /><br />
+     * The first argument specifies the receipient's 
+     * e-mail address. The optional second argument 
+     * specifies the name of the recipient.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.addBCC("hop@helma.at");
+     * mail.addBCC("tobi@helma.at", "Tobi Schaefer");</pre>
+     * 
+     * @param {String} addstr as String, receipients email address
+     * @param {String} name as String, optional receipients name
+     */
     this.addBCC = function(addstr, name) {
         try {
             addRecipient(addstr, name, Message.RecipientType.BCC);
@@ -173,6 +270,15 @@ helma.Mail = function(smtp) {
         return;
     }
 
+    /**
+     * Sets the subject of an e-mail message.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setSubject("Hello, World!");</pre>
+     * 
+     * @param {String} subject as String, the email subject
+     */
     this.setSubject = function(subject) {
         if (!subject) {
             return;
@@ -186,6 +292,16 @@ helma.Mail = function(smtp) {
         return;
     };
 
+    /**
+     * Sets the body text of an e-mail message.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail();
+     * mail.setText("Hello, World!");</pre>
+     * 
+     * @param {String} text as String, to be appended to the message body
+     * @see #addText
+     */
     this.setText = function(text) {
         if (text) {
             buffer = new java.lang.StringBuffer(text);
@@ -193,6 +309,16 @@ helma.Mail = function(smtp) {
         return;
     };
 
+    /**
+     * Appends a string to the body text of an e-mail message.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new Mail();
+     * mail.addText("Hello, World!");</pre>
+     * 
+     * @param {String} text as String, to be appended to the message body
+     * @see #setText
+     */
     this.addText = function(text) {
         if (buffer == null) {
             buffer = new java.lang.StringBuffer(text);
@@ -202,6 +328,35 @@ helma.Mail = function(smtp) {
         return;
     };
 
+    /**
+     * Adds an attachment to an e-mail message.
+     * <br /><br />
+     * The attachment needs to be either a MIME Object or a java.io.file object.
+     * <br /><br />
+     * Use the getURL() function to retrieve a MIME object or wrap a 
+     * java.io.File object around a file of the local file system.
+     * <br /><br />
+     * Example:
+     * <pre>var file1 = getURL("http://localhost:8080/static/image.gif");
+     * var file2 = getURL("file:////home/snoopy/woodstock.jpg");
+     * var file3 = new java.io.File("/home/snoopy/woodstock.jpg");
+     * var mail = new Mail();
+     * mail.addPart(file1);
+     * mail.addPart(file2);
+     * mail.addPart(file3);
+     * &nbsp;
+     * mail.setFrom("snoopy@doghouse.com");
+     * mail.setTo("woodstock@birdcage.com");
+     * mail.setSubject("Look at this!");
+     * mail.addText("I took a photograph from you. Neat, isn't it? -Snoop");
+     * mail.send();</pre>
+     * 
+     * @param {fileOrMimeObject} File or Mime object to attach to the email
+     * @param {String} nameString as String, optional name of the attachment
+     * @see global.getUrl
+     * @see mimePart
+     * @see java.io.File
+     */
     this.addPart = function(obj, filename) {
         try {
             if (obj == null) {
@@ -251,6 +406,28 @@ helma.Mail = function(smtp) {
         return;
     }
 
+    /**
+     * Sends an e-mail message.
+     * <br /><br />
+     * This function sends the message using the SMTP 
+     * server as specified when the Mail object was 
+     * constructed using helma.Mail.
+     * <br /><br />
+     * If no smtp hostname was specified when the Mail
+     * object was constructed, the smtp property in either  
+     * the app.properties or server.properties file needs 
+     * to be set in order for this to work.
+     * <br /><br />
+     * Example:
+     * <pre>var mail = new helma.Mail('smtp.example.com');
+     * mail.setTo("watching@michi.tv", "michi");
+     * mail.addCC("franzi@home.at", "franzi");
+     * mail.addBCC("monie@home.at");
+     * mail.setFrom("chef@frischfleisch.at", "Hannes");
+     * mail.setSubject("Registration Conformation");
+     * mail.addText("Thanks for your Registration...");
+     * mail.send();</pre>
+     */
     this.send = function() {
         if (this.status > OK) {
             res.debug(errStr + ".send(): Status is " + this.status);
@@ -287,11 +464,13 @@ helma.Mail = function(smtp) {
 }
 
 
+/** @ignore */
 helma.Mail.toString = function() {
     return "[helma.Mail]";
 };
 
 
+/** @ignore */
 helma.Mail.prototype.toString = function() {
     return "[helma.Mail Object]";
 };