make helpers docs more consistent; add a test

src/helpers/deepExtend.js

@@ -1,10 +1,10 @@
 import extend from './extend'
 /**
- * A more semantic convenience function. Delegates to {@link helpers#extend} and passes `true` as the first argument. Recursively merge the contents of two or more objects together into the first object.
+ * A more semantic convenience function. Delegates to {@link extend} and passes `true` as the first argument. Deep merge the contents of two or more objects together into the first object.
  *
  * @function deepExtend
  * @param {Object} destination The object to modify
- * @param {Object} source The object whose contents to take
+ * @param {Object} source The object whose keys to take
  * @param {Object} [source2] Optional, You can add any number of objects as arguments.
  * @returns {Object} result The merged object. Note that the `destination` object will always be modified.
  *

src/helpers/discernFileFormatter.js

@@ -2,18 +2,18 @@ import discernFormat from './discernFormat'
 import formatters from '../formatters/index'
 
 /**
- * Returns a formatter that will format json data to file type specified by the extension in `fileName`. Used internally by `.writeData` and `.writeDataSync`.
+ * Returns a formatter that will format json data to file type specified by the extension in `filePath`. Used internally by {@link writeData} and {@link writeDataSync}.
  *
  * @function discernFileFormatter
  * @param {String} filePath Input file path
- * @returns {Object} a formatter that can write the file
+ * @returns {Function} A formatter function that will write the extension format
  *
  * @example
  * var formatter = io.discernFileFormatter('path/to/data.tsv')
  * var csv = formatter(json)
  */
-export default function discernFileFormatter (fileName) {
-  var format = discernFormat(fileName)
+export default function discernFileFormatter (filePath) {
+  var format = discernFormat(filePath)
   var formatter = formatters[format]
   // If we don't have a parser for this format, return as text
   if (typeof formatter === 'undefined') {

src/helpers/discernFormat.js

@@ -1,20 +1,25 @@
 import {extname} from '../utils/path'
 
 /**
- * Given a `fileName` return its file extension. Used internally by `.discernPaser` and `.discernFileFormatter`.
+ * Given a `filePath` return the file's extension. Used internally by {@link discernParser} and {@link discernFileFormatter}. Returns `false` for files without an extension, including dotfiles
  *
  * @function discernFormat
  * @param {String} filePath Input file path
- * @returns {String} the file's extension
+ * @returns {String} The file's extension
  *
  * @example
  * var format = io.discernFormat('path/to/data.csv')
  * console.log(format) // 'csv'
+ *
+ * @example
+ * var format = io.discernFormat('path/to/.dotfile')
+ * console.log(format) // false
  */
-export default function discernFormat (fileName) {
-  var extension = extname(fileName)
-  if (extension === '') return false
+export default function discernFormat (filePath) {
+  var ext = extname(filePath)
+  if (ext === '') return false
 
-  var formatName = extension.slice(1)
+  // Chop '.' off extension returned by extname
+  var formatName = ext.slice(1)
   return formatName
 }

src/helpers/discernParser.js

@@ -3,24 +3,24 @@ import discernFormat from './discernFormat'
 import parsers from '../parsers/index'
 
 /**
- * Given a `fileName` return a parser that can read that file as json. Parses as text if format not supported by a built-in parser. If given a delimter string as the second argument, return a parser for that delimiter regardless of `fileName`. Used internally by `.readData` and `.readDataSync`.
+ * Given a `filePath` return a parser that can read that file as json. Parses as text if format not supported by a built-in parser. If given a delimter string as the second argument, return a parser for that delimiter regardless of `filePath`. Used internally by {@link readData} and {@link readDataSync}.
  *
  * @function discernParser
- * @param {String} filePath Input file path
- * @param {String} delimiter Alternative usage is to pass a delimiter string. Delegates to `dsv.dsvFormat`.
- * @returns {Object} a parser that can read the file
+ * @param {String} [filePath] Input file path
+ * @param {String} [delimiter] Alternative usage is to pass a delimiter string. Delegates to `dsv.dsvFormat`.
+ * @returns {Function} A parser that can read the file
  *
  * @example
  * var parser = io.discernParser('path/to/data.csv')
  * var json = parser('path/to/data.csv')
  * var parser = io.discernParser(null, '_')
  * var json = parser('path/to/data.usv')
  */
-export default function discernParser (fileName, delimiter) {
+export default function discernParser (filePath, delimiter) {
   if (delimiter) {
     return dsvFormat(delimiter).parse
   }
-  var format = discernFormat(fileName)
+  var format = discernFormat(filePath)
   var parser = parsers[format]
   // If we don't have a parser for this format, return as text
   if (typeof parser === 'undefined') {

src/helpers/exists.js

@@ -5,7 +5,7 @@ import fs from 'fs'
  *
  * @function exists
  * @param {String} filePath Input file path
- * @param {Function} callback has the signature `(err, exists)`
+ * @param {Function} callback Has signature `(err, exists)`
  *
  * @example
  * var exists = io.exists('path/to/data.tsv', function (err, exists) {

src/helpers/existsSync.js

@@ -1,11 +1,11 @@
 import fs from 'fs'
 
 /**
- * Syncronous version of {@link helpers#exists}. Falls back to `fs.existsSync` if that function exists
+ * Syncronous version of {@link exists}. Delegates to `fs.existsSync` if that function is available.
  *
  * @function existsSync
  * @param {String} filePath Input file path
- * @returns {Boolean} whether the file exists or not
+ * @returns {Boolean} Whether the file exists or not
  *
  * @example
  * var exists = io.existsSync('path/to/data.tsv')

src/helpers/extMatchesStr.js

@@ -6,7 +6,7 @@ import {extname} from '../utils/path'
  * @function extMatchesStr
  * @param {String} filePath Input file path
  * @param {String} extension The extension to test. An empty string will match a file with no extension.
- * @returns {Boolean} whether The extension matched or not.
+ * @returns {Boolean} Whether it matched or not.
  *
  * @example
  * var matches = io.extMatchesStr('path/to/data.tsv', 'tsv')

src/helpers/extend.js

@@ -4,7 +4,7 @@
  * @function extend
  * @param {Boolean} [deepExtend] Optional, set to `true` to merge recursively.
  * @param {Object} destination The object to modify
- * @param {Object} source The object whose contents to take
+ * @param {Object} source The object whose keys to take
  * @param {Object} [source2] Optional, You can add any number of objects as arguments.
  * @returns {Object} result The merged object. Note that the `destination` object will always be modified.
  *

src/helpers/makeDirectories.js

@@ -2,7 +2,7 @@ import mkdirp from 'mkdirp'
 import {dirname} from '../utils/path'
 
 /**
- * Asynchronously Create directories in a given file path
+ * Asynchronously create directories along a given file path. Delegates to [mkdirp](http://npmjs.org/package/mkdirp) module
  *
  * @function makeDirectories
  * @param {String} outPath The path to a file

src/helpers/makeDirectoriesSync.js

@@ -2,7 +2,7 @@ import mkdirp from 'mkdirp'
 import {dirname} from '../utils/path'
 
 /**
- * Synchronous version of `makeDirectories`
+ * Synchronous version of {link #makeDirectories}. Delegates to [mkdirp](http://npmjs.org/package/mkdirp) module
  *
  * @function makeDirectoriesSync
  * @param {String} outPath The path to a file

src/helpers/matches.js

@@ -3,11 +3,11 @@ import matchesRegExp from './matchesRegExp'
 import isRegExp from '../utils/isRegExp'
 
 /**
- * Test whether a file name or path matches a given matcher. Delegates to {@link helpers#extMatches} if `matcher` is a string` and tests only against the file name extension. Delegates to {@link helpers#extMatchRegEx} if matcher is a Regular Expression and tests against entire string, which is usefulf or testing the full file path.
+ * Test whether a file name or path matches a given matcher. Delegates to {@link extMatchesStr} if `matcher` is a string` and tests only against the file name extension. Delegates to {@link matchesRegExp} if matcher is a Regular Expression and tests against entire string, which is usefulf or testing the full file path.
  *
  * @function matches
  * @param {String} filePath Input file path or path to the file.
- * @returns {String} matcher The string to match with.
+ * @returns {String|RegExp} matcher The string or Regular Expression to match against.
  *
  * @example
  * var matches = io.matches('path/to/data.tsv', 'tsv')

src/helpers/matchesRegExp.js

@@ -3,8 +3,8 @@
  *
  * @function matchesRegExp
  * @param {String} filePath Input file path or file path.
- * @param {RegExp} RegEx The RegEx to match with.
- * @returns {Boolean} whether The string matches the RegEx.
+ * @param {RegExp} RegExp The Regular Expression to match against.
+ * @returns {Boolean} Whether they match.
  *
  * @example
  * var matches = io.matchesRegExp('.gitignore', /\.gitignore/)

src/readers/readDataSync.js

@@ -6,7 +6,7 @@ import {formatsIndex} from '../config/equivalentFormats'
 import _ from 'underscore'
 
 /**
- * Syncronous version of {@link readers#readData}
+ * Syncronous version of {@link readData}
  *
  * @function readDataSync
  * @param {String} filePath Input file path

test/test.js

@@ -71,6 +71,9 @@ describe('discernFormat()', function () {
     it('should be false', function () {
       assert.equal(io.discernFormat('/fake/path/what_is_this_file'), false)
     })
+    it('should be false for dotfiles', function () {
+      assert.equal(io.discernFormat('/fake/path/.gitignore'), false)
+    })
   })
 
   describe('csv', function () {