cleaning up code comments

Author: mrodrig

lib/converter.js

@@ -3,6 +3,7 @@
 var json2Csv = require('./json-2-csv'), // Require our json-2-csv code
     csv2Json = require('./csv-2-json'), // Require our csv-2-json code
     constants = require('./constants'), // Require in constants
+    Promise = require('bluebird'),
     _ = require('underscore'); // Require underscore
 
 /**
@@ -17,8 +18,10 @@ var defaultOptions = constants.DefaultOptions;
  */
 var buildOptions = function (opts, cb) {
     opts = _.defaults(opts || {}, defaultOptions);
+
     // Note: _.defaults does a shallow default, we need to deep copy the DELIMITER object
     opts.DELIMITER = _.defaults(opts.DELIMITER || {}, defaultOptions.DELIMITER);
+
     // If the delimiter fields are the same, report an error to the caller
     if (opts.DELIMITER.FIELD === opts.DELIMITER.ARRAY) { return cb(new Error(constants.Errors.delimitersMustDiffer)); }
     // Otherwise, send the options back
@@ -28,17 +31,22 @@ var buildOptions = function (opts, cb) {
 // Export the following functions that will be client accessible
 module.exports = {
 
-    // Client accessible json2csv function
-    // Takes an array of JSON documents to be converted,
-    // a callback that will be called with (err, csv) after
-    // processing is completed, and optional options
+    /**
+     * Client accessible json2csv function
+     * Takes an array of JSON documents to be converted, a callback that will be called with (err, csv)
+     * after processing is complete, and optional options
+     * @param array Object[] data to be converted
+     * @param callback Function callback
+     * @param opts Object options object
+     */
     json2csv: function (array, callback, opts) {
         // If this was promisified (callback and opts are swapped) then fix the argument order.
         if (_.isObject(callback) && !_.isFunction(callback)) {
             var func = opts;
             opts = callback;
             callback = func;
         }
+
         buildOptions(opts, function (err, options) { // Build the options
             if (err) {
                 return callback(err);
@@ -49,17 +57,22 @@ module.exports = {
     },
 
 
-    // Client accessible csv2json function
-    // Takes a string of CSV to be converted to a JSON document array,
-    // a callback that will be called with (err, csv) after
-    // processing is completed, and optional options
+    /**
+     * Client accessible csv2json function
+     * Takes a string of CSV to be converted to a JSON document array, a callback that will be called
+     * with (err, json) after processing is complete, and optional options
+     * @param csv
+     * @param callback
+     * @param opts
+     */
     csv2json: function (csv, callback, opts) {
         // If this was promisified (callback and opts are swapped) then fix the argument order.
         if (_.isObject(callback) && !_.isFunction(callback)) {
             var func = opts;
             opts = callback;
             callback = func;
         }
+
         buildOptions(opts, function (err, options) { // Build the options
             if (err) {
                 return callback(err);

lib/csv-2-json.js

@@ -5,7 +5,12 @@ var _ = require('underscore'),
 
 var options = {}; // Initialize the options - this will be populated when the csv2json function is called.
 
-// Generate the JSON heading from the CSV
+/**
+ * Generate the JSON heading from the CSV
+ * @param lines
+ * @param callback
+ * @returns {*}
+ */
 var retrieveHeading = function (lines, callback) {
     if (!lines.length) { // If there are no lines passed in, then throw an error
         return callback(new Error(constants.Errors.csv2json.noDataRetrieveHeading)); // Pass an error back to the user
@@ -20,7 +25,13 @@ var retrieveHeading = function (lines, callback) {
     return heading;
 };
 
-// Add a nested key and its value in the given document
+/**
+ * Add a nested key and its value in the given document
+ * @param key String
+ * @param value String
+ * @param doc Object
+ * @returns {*}
+ */
 var addNestedKey = function (key, value, doc) {
     var subDocumentRoot = doc, // This is the document that we will be using to add the nested keys to.
         trackerDocument = subDocumentRoot, // This is the document that will use to iterate through the subDocument, starting at the root
@@ -43,10 +54,20 @@ var keyExists = function (key, doc) {
     return (!_.isUndefined(doc[key])); // If the key doesn't exist, then the type is 'undefined'
 };
 
+/**
+ * Does the given value represent an array?
+ * @param value
+ * @returns {*|boolean}
+ */
 var isArrayRepresentation = function (value) {
     return (value && value.indexOf('[') === 0 && value.lastIndexOf(']') === value.length-1);
 };
 
+/**
+ * Converts the value from a CSV 'array'
+ * @param val
+ * @returns {Array}
+ */
 var convertArrayRepresentation = function (val) {
     val = _.filter(val.substring(1, val.length-1).split(options.DELIMITER.ARRAY), function (value) {
         return value;
@@ -59,7 +80,13 @@ var convertArrayRepresentation = function (val) {
     return val;
 };
 
-// Create a JSON document with the given keys (designated by the CSV header) and the values (from the given line)
+/**
+ * Create a JSON document with the given keys (designated by the CSV header)
+ *   and the values (from the given line)
+ * @param keys String[]
+ * @param line String
+ * @returns {Object} created json document
+ */
 var createDoc = function (keys, line) {
     if (line == '') { return false; } // If we have an empty line, then return false so we can remove all blank lines (falsy values)
     var doc = {}, // JSON document to start with and manipulate
@@ -79,7 +106,12 @@ var createDoc = function (keys, line) {
     return doc; // Return the created document
 };
 
-// Main wrapper function to convert the CSV to the JSON document array
+/**
+ * Main helper function to convert the CSV to the JSON document array
+ * @param lines String[]
+ * @param callback Function callback function
+ * @returns {Array}
+ */
 var convertCSV = function (lines, callback) {
     var generatedHeaders = retrieveHeading(lines, callback), // Retrieve the headings from the CSV, unless the user specified the keys
         jsonDocs = [], // Create an array that we can add the generated documents to
@@ -93,21 +125,47 @@ var convertCSV = function (lines, callback) {
     return _.filter(jsonDocs, function (doc) { return doc !== false; }); // Return all non 'falsey' values to filter blank lines
 };
 
+/**
+ * Validates the input provided to csv2json.
+ * Only returns (undefined) if no errors are found
+ * @param opts Object options object
+ * @param data String csv string
+ * @param callback Function callback function
+ * @returns {*}
+ */
+var checkErrors = function (opts, data, callback){
+
+};
+
 module.exports = {
 
-    // Function to export internally
-    // Takes options as a document, data as a CSV string, and a callback that will be used to report the results
+    /**
+     * Internally exported csv2json function
+     * Takes options as a document, data as a CSV string, and a callback that will be used to report the results
+     * @param opts Object options object
+     * @param data String csv string
+     * @param callback Function callback function
+     */
     csv2json: function (opts, data, callback) {
-        if (!callback) { throw new Error(constants.Errors.callbackRequired); } // If a callback wasn't provided, throw an error
-        if (!opts) { return callback(new Error(constants.Errors.optionsRequired)); return null; } // Shouldn't happen, but just in case
-        else { options = opts; } // Options were passed, set the global options value
-        if (!data) { return callback(new Error(constants.Errors.csv2json.cannotCallCsv2JsonOn + data + '.')); return null; } // If we don't receive data, report an error
-        if (!_.isString(data)) { // The data is not a string
+        // If a callback wasn't provided, throw an error
+        if (!callback) { throw new Error(constants.Errors.callbackRequired); }
+
+        // Shouldn't happen, but just in case
+        if (!opts) { return callback(new Error(constants.Errors.optionsRequired)); return null; }
+        options = opts; // Options were passed, set the global options value
+
+        // If we don't receive data, report an error
+        if (!data) { return callback(new Error(constants.Errors.csv2json.cannotCallCsv2JsonOn + data + '.')); return null; }
+
+        // The data provided is not a string
+        if (!_.isString(data)) {
             return callback(new Error(constants.Errors.csv2json.csvNotString)); // Report an error back to the caller
         }
-        var lines = data.split(options.EOL); // Split the CSV into lines using the specified EOL option
-        var json = convertCSV(lines, callback); // Retrieve the JSON document array
-        callback(null, json); // Send the data back to the caller
+
+        // Split the CSV into lines using the specified EOL option
+        var lines = data.split(options.EOL),
+            json = convertCSV(lines, callback); // Retrieve the JSON document array
+        return callback(null, json); // Send the data back to the caller
     }
 
 };