Added comments, replaced mergeObjects with lodash function

lib/SendGridCompatibility/Email.js

@@ -1,11 +1,22 @@
 'use strict';
 
+/**
+ * Email object constructor
+ *
+ * @param options object that contains initial values
+ */
 function Email(options){
   for (var option in options) {
     this[option] = options[option];
   }
 }
 
+/**
+ * Sendgrid email compatibility functions
+ *
+ * @param Most have a single value to map
+ * Add functions will often contain a key / value pair
+ */
 Email.prototype.addTo = function (address){
   if (this.to === undefined){
     this.to = address;
@@ -59,24 +70,31 @@ Email.prototype.addSection = function (key, value){
 Email.prototype.setSections = function (sections){
   this.section = sections;
 };
+// Sparkpost doesn't currently support addUniqueArg, throw an error
 Email.prototype.addUniqueArg = function (){
   throw new Error('Unique Argument compatibility is not supported.');
 };
+// Sparkpost doesn't currently support setUniqueArgs, throw an error
 Email.prototype.setUniqueArgs = function (){
   throw new Error('Unique Argument compatibility is not supported.');
 };
+// Sparkpost doesn't currently support addCategory, throw an error
 Email.prototype.addCategory = function (){
   throw new Error('Category compatibility is not supported.');
 };
+// Sparkpost doesn't currently support setCategories, throw an error
 Email.prototype.setCategories = function (){
   throw new Error('Category compatibility is not supported.');
 };
+// Sparkpost doesn't currently support addFilter, throw an error
 Email.prototype.addFilter = function (){
   throw new Error('Filter compatibility is not supported.');
 };
+// Sparkpost doesn't currently support setFilters, throw an error
 Email.prototype.setFilters = function (){
   throw new Error('Filter compatibility is not supported.');
 };
+// Sparkpost doesn't currently support addFile, throw an error
 Email.prototype.addFile = function (){
   throw new Error('File compatibility is not supported.');
 };

lib/SendGridCompatibility/index.js

@@ -1,8 +1,18 @@
 'use strict';
-
+var _ = require('lodash');
 var transmission = require('../transmission');
 var configuration = require('../configuration');
 
+/**
+ * Sendgrid compatibility constructor
+ * Responsible for taking the api key and config options and
+ * translating them into a format compatible with sparkpost's
+ * configuration.setConfig function.
+ *
+ * @param username: dropped sendgrid username string
+ * @param apiKey: api key string
+ * @param options: optional additional options object
+ */
 var sendgrid = function(username, apiKey, options) {
   var configOptions = options;
   if (configOptions === undefined) {
@@ -14,6 +24,13 @@ var sendgrid = function(username, apiKey, options) {
   configuration.setConfig(configOptions);
 };
 
+/**
+ * Private Method for translating a user's sendgrid config options
+ * to a sparkpost compatible set by dropping unnecessary data
+ *
+ * @param payload: sendgrid formatted config options object
+ * @returns object: config options with incompatible entries removed
+ */
 var translateConfig = function(options) {
   var translated = {};
   if (options.host !== undefined) {
@@ -28,21 +45,18 @@ var translateConfig = function(options) {
   return translated;
 };
 
-var mergeObjects = function(obj1, obj2){
-  var merged = {};
-  for (var key1 in obj1) {
-    merged[key1] = obj1[key1];
-  }
-  for (var key2 in obj2) {
-    merged[key2] = obj2[key2];
-  }
-  return merged;
-};
-
+/**
+ * Private Method for translating a user's sendgrid substitutions and sections
+ * to a consolidated sparkpost substitutionData object
+ *
+ * @param payload: sendgrid formatted object or sendgrid Email object to
+ * be translated into a sparkpost payload
+ * @returns object: substitutionData object as per sparkpost payload format
+ */
 var consolidateSubstitutionData = function(payload) {
   var substitutionData = {};
   if (payload.sub !== undefined && payload.section !== undefined){
-    substitutionData = mergeObjects(payload.sub, payload.section);
+    substitutionData = _.merge(payload.sub, payload.section);
   } else if (payload.sub !== undefined){
     substitutionData = payload.sub;
   } else if (payload.section !== undefined){
@@ -51,6 +65,14 @@ var consolidateSubstitutionData = function(payload) {
   return substitutionData;
 };
 
+/**
+ * Private Method for translating a user's sendgrid to and toname to a recipients
+ * array that the transmissions "Class" can understand
+ *
+ * @param payload: sendgrid formatted object or sendgrid Email object to
+ * be translated into a sparkpost payload
+ * @returns array: recipients array as per sparkpost payload format
+ */
 var parseTo = function(payload){
   var recipients = [];
   if (typeof payload.to === 'string'){
@@ -70,6 +92,14 @@ var parseTo = function(payload){
   return recipients;
 };
 
+/**
+ * Private Method for translating a user's sendgrid payload to a format
+ * that the transmissions "Class" can understand
+ *
+ * @param payload: sendgrid formatted object or sendgrid Email object to
+ * be translated into a sparkpost payload
+ * @returns object: translation from sendgrid payload to sparkpost payload
+ */
 var translatePayload = function(payload) {
   var sub = consolidateSubstitutionData(payload)
     , input = {
@@ -97,6 +127,14 @@ var translatePayload = function(payload) {
   return input;
 };
 
+/**
+ * An exposed function of SendGridCompatibility that calls upon
+ * private helper methods to translate an Email or inline object
+ * and then pass that content to the transmissions send function.
+ *
+ * @param payload: sendgrid formatted object or sendgrid Email object to
+ * be translated into a sparkpost payload and sent
+ */
 sendgrid.prototype.send = function(payload, callback) {
   var translated = translatePayload(payload);
   transmission.send(translated, function (err, res){