Merge pull request #15 from partkyle/documentation

Documentation

1 files changed, 67 insertions, 13 deletions

diff --git a/lib/sendgrid.js b/lib/sendgrid.js
index 07557ea..6ce98ec 100644
--- a/lib/sendgrid.js
+++ b/lib/sendgrid.js
@@ -4,28 +4,35 @@ var querystring = require('querystring');
 var https = require('https');
 var nodemailer = require('nodemailer');
 var _ = require('underscore');
-var fs = require('fs');
 var path = require('path');
 var mime = require('mime');
 
 var Email = require('./email');
 
-function SendGrid(credentials) {
-  this.api_user = credentials.api_user;
-  this.api_key = credentials.api_key;
+/*
+ * Class for handling communications with SendGrid.
+ *
+ * @param  {String}  api_user  The SendGrid username.
+ * @param  {String}  api_key   The key credentials for SendGrid.
+ */
+function SendGrid(api_user, api_key) {
+  this.api_user = api_user;
+  this.api_key = api_key;
 }
 
-var boundary = Math.random();
-
 /*
- * Sends an email and returns true if the
+ * Sends an email via REST and returns true if the
  * message was sent successfully.
  *
- * @returns {Boolean}
-*/
+ * @param    {Email|Object}  email     An email object or a hash that has
+ *                                    the values for the email to be sent.
+ * @param    {Function}      callback  A function to call when the processing is done.
+ */
 SendGrid.prototype.send = function(email, callback) {
   var self = this;
 
+  var boundary = Math.random();
+
   if (email.constructor !== Email) {
     email = new Email(email);
   }
@@ -38,7 +45,7 @@ SendGrid.prototype.send = function(email, callback) {
       method: 'POST',
     };
     if (email.hasFiles()) {
-      post_data = self.getMultipartData(email);
+      post_data = self.getMultipartData(email, boundary);
       var length = 0;
       for (var buf in post_data) {
         length += post_data[buf].length;
@@ -86,6 +93,14 @@ SendGrid.prototype.send = function(email, callback) {
   }
 };
 
+/*
+ * Sends an email via SMTP and returns true if the
+ * message was sent successfully.
+ *
+ * @param    {Email|Object}  email     An email object or a hash that has
+ *                                     the values for the email to be sent.
+ * @param    {Function}      callback  A function to call when the processing is done.
+ */
 SendGrid.prototype.smtp = function(email, callback) {
   var self = this;
 
@@ -121,6 +136,16 @@ SendGrid.prototype.smtp = function(email, callback) {
   }
 };
 
+/*
+ * Function for internal use.
+ *
+ * Used for returning the parameters for sending an email via REST.
+ *
+ * This method is only used when there are no attachments on the email object.
+ *
+ * @param   {Email}  email  The email object to be sent via REST.
+ * @return  {String}        Querystring format of the email to be sent.
+ */
 SendGrid.prototype.getPostData = function(email) {
   var data = {
     api_user: this.api_user,
@@ -132,7 +157,19 @@ SendGrid.prototype.getPostData = function(email) {
   return querystring.stringify(data);
 };
 
-SendGrid.prototype.getMultipartData = function(email) {
+/*
+ * Function for internal use.
+ *
+ * Used for returning the parameters for sending an email via REST.
+ *
+ * This method is used when there are attachments on the email object.
+ *
+ * @param   {Email}   email     The email object to be sent via REST.
+ * @param   {String}  boundary  The boundary to use between multipart sections.
+ * @return  {Array[Buffer]}     An array of buffers for each section of
+ *                              the multipart/form-data request.
+ */
+SendGrid.prototype.getMultipartData = function(email, boundary) {
   var data = [];
   data.push(new Buffer(encodeField(boundary, 'api_user', this.api_user)));
   data.push(new Buffer(encodeField(boundary, 'api_key', this.api_key)));
@@ -150,14 +187,31 @@ SendGrid.prototype.getMultipartData = function(email) {
   return data;
 };
 
-function encodeField(boundary,name,value) {
+/*
+ * Function for encoding a field as a multipart/form-data request.
+ *
+ * @param   {String}  boundary  The boundary to use between requests.
+ * @param   {String}  name      The name of the parameter.
+ * @param   {String}  value     The value of the parameter.
+ * @return  {String}            The string representing the multipart/form-data section.
+ */
+function encodeField(boundary, name, value) {
     var return_part = "--" + boundary + "\r\n";
     return_part += "Content-Disposition: form-data; name=\"" + name + "\"\r\n\r\n";
     return_part += value + "\r\n";
     return return_part;
 }
 
-function encodeFile(boundary,type,name,filename) {
+/*
+ * Function for encoding a file as a multipart/form-data request.
+ *
+ * @param   {String}  boundary  The boundary to use between requests.
+ * @param   {String}  type      The Content-Type of the file
+ * @param   {String}  name      The name of the parameter.
+ * @param   {String}  filename  The name of the file.
+ * @return  {String}            The string representing the multipart/form-data section.
+ */
+function encodeFile(boundary, type, name, filename) {
     var return_part = "--" + boundary + "\r\n";
     return_part += "Content-Disposition: form-data; name=\"" + name + "\"; filename=\"" + filename + "\"\r\n";
     return_part += "Content-Type: " + type + "\r\n\r\n";