added documentation and changed the constructor of the SendGrid object

1 files changed, 63 insertions, 8 deletions

diff --git a/lib/sendgrid.js b/lib/sendgrid.js
index 1ad92a6..3eabc8e 100644
--- a/lib/sendgrid.js
+++ b/lib/sendgrid.js
@@ -9,17 +9,25 @@ 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;
 }
 
 /*
- * 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;
 
@@ -81,6 +89,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;
 
@@ -116,6 +132,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,
@@ -127,6 +153,18 @@ SendGrid.prototype.getPostData = function(email) {
   return querystring.stringify(data);
 };
 
+/*
+ * 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)));
@@ -145,14 +183,31 @@ SendGrid.prototype.getMultipartData = function(email, boundary) {
   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";