add @function for better doc signatures

docs/assets/split.css

@@ -34,3 +34,7 @@ section{
   font-size: 2em;
   color: #416381;
 }
+.signature{
+  font-weight: normal;
+}
+

docs/default_theme/assets/split.css

@@ -34,3 +34,7 @@ section{
   font-size: 2em;
   color: #416381;
 }
+.signature{
+  font-weight: normal;
+}
+

docs/default_theme/section._

@@ -3,8 +3,8 @@
   <% if (typeof nested === 'undefined' || (section.context && section.context.github)) { %>
   <div class='clearfix'>
     <% if (typeof nested === 'undefined') { %>
-    <h3 class='fl m0' id='<%- slug(section.namespace) %>'>
-      <%- section.name %>
+    <h3 class='fl m0 signature' id='<%- slug(section.namespace) %>'>
+      io.<%= signature(section).replace(section.name, a => '<span class="bold">' + a + '</span>') %>
     </h3>
     <% } %>
     <% if (section.context && section.context.github) { %>
@@ -17,7 +17,6 @@
 
   <%= md(section.description) %>
 
-  <div class='pre p1 fill-light mt0'><%= signature(section) %></div>
   <% if (section.type) { %>
     <p>
       Type:

src/converters/convertDbfToData.js

@@ -4,6 +4,7 @@ import writeData from '../writers/writeData'
 /**
  * Reads in a dbf file with `.readDbf` and write to file using `.writeData`. A convenience function for converting DBFs to more useable formats. Formerly known as `writeDbfToData` and is aliased for legacy support.
  *
+ * @function convertDbfToData
  * @param {String} inFileName the input file name
  * @param {String} outFileName the output file name
  * @param {Object} [options] Optional config object, see below

src/helpers/deepExtend.js

@@ -2,6 +2,7 @@ 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.
  *
+ * @function deepExtend
  * @param {Object} destination The object to modify
  * @param {Object} source The object whose contents to take
  * @param {Object} [source2] Optional, You can add any number of objects as arguments.

src/helpers/discernFileFormatter.js

@@ -3,6 +3,8 @@ 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`.
+ *
+ * @function discernFileFormatter
  * @param {String} fileName the name of the file
  * @returns {Object} a formatter that can write the file
  *

src/helpers/discernParser.js

@@ -4,6 +4,8 @@ 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`.
+ *
+ * @function discernParser
  * @param {String} fileName the name of the file
  * @param {String} delimiter Alternative usage is to pass a delimiter string. Delegates to `dsv.dsvFormat`.
  * @returns {Object} a parser that can read the file

src/helpers/exists.js

@@ -2,6 +2,8 @@ import fs from 'fs'
 
 /**
  * Asynchronously test whether a file exists or not by using `fs.access` modified from https://github.com/nodejs/io.js/issues/1592#issuecomment-98392899.
+ *
+ * @function exists
  * @param {String} fileName the name of the file
  * @param {Function} callback has the signature `(err, exists)`
  *

src/helpers/existsSync.js

@@ -3,6 +3,7 @@ import fs from 'fs'
 /**
  * Syncronous version of {@link helpers#exists}. Falls back to `fs.existsSync` if that function exists
  *
+ * @function existsSync
  * @param {String} fileName the name of the file
  * @returns {Boolean} whether the file exists or not
  *

src/helpers/extMatchesStr.js

@@ -3,6 +3,7 @@ import {extname} from '../utils/path'
 /**
  * Test whether a file name has the given extension
  *
+ * @function extMatchesStr
  * @param {String} fileName The name of the file.
  * @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.

src/helpers/extend.js

@@ -1,6 +1,7 @@
 /**
  * A port of jQuery's extend. Merge the contents of two or more objects together into the first object. Supports deep extending with `true` as the first argument.
  *
+ * @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

src/helpers/makeDirectories.js

@@ -4,6 +4,7 @@ import {dirname} from '../utils/path'
 /**
  * Asynchronously Create directories in a given file path
  *
+ * @function makeDirectories
  * @param {String} outPath The path to a file
  * @param {Function} callback The function to do once this is done. Has signature of `(err)`
  *

src/helpers/makeDirectoriesSync.js

@@ -4,6 +4,7 @@ import {dirname} from '../utils/path'
 /**
  * Synchronous version of `makeDirectories`
  *
+ * @function makeDirectoriesSync
  * @param {String} outPath The path to a file
  *
  * @example

src/helpers/matches.js

@@ -5,6 +5,7 @@ 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.
  *
+ * @function matches
  * @param {String} fileName The name of the file or path to the file.
  * @returns {String} matcher The string to match with.
  *

src/helpers/matchesRegExp.js

@@ -1,6 +1,7 @@
 /**
  * Test whether a string matches a given Regular Expression.
  *
+ * @function matchesRegExp
  * @param {String} fileName The name of the file or file path.
  * @param {RegExp} RegEx The RegEx to match with.
  * @returns {Boolean} whether The string matches the RegEx.

src/readers/readData.js

@@ -21,6 +21,7 @@ import _ from 'underscore'
  *
  * *Note: Does not currently support `.dbf` files. `.yaml` and `.yml` formats are read with js-yaml's `.load` method, which has no security checking. See js-yaml library for more secure options.*
  *
+ * @function readData
  * @param {String} fileName the name of the file
  * @param {Object|Function} [parserOptions] Optional. Set this as a function as a shorthand for `map`.
  * @param {String|Function|Object} [parserOptions.parser] optional This can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method that's a function.

src/readers/readDataSync.js

@@ -8,6 +8,7 @@ import _ from 'underscore'
 /**
  * Syncronous version of {@link readers#readData}
  *
+ * @function readDataSync
  * @param {String} fileName the name of the file
  * @param {Function|Object} [parserOptions] Can be a map function, or an object specifying other options.
  * @param {String|Function|Object} [parserOptions.parser] optional This can be a string that is the file's delimiter or a function that returns the json. See `parsers` in library source for examples. For convenience, this can also take a dsv object such as `dsv.dsv('_')` or any object that has a `parse` method that's a function.

src/readers/readDbf.js

@@ -4,6 +4,7 @@ import identity from '../utils/identity'
 /**
  * Asynchronously read a dbf file. Returns an empty array if file is empty.
  *
+ * @function readDbf
  * @param {String} fileName the name of the file
  * @param {Function|Object} [map] Optional map function or object with `map` key that is a function, called once for each row (header row skipped). Has signature `(row)`. See example below.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read

src/readers/readdirFilter.js

@@ -3,6 +3,7 @@ import readdir from './readdir'
 /**
  * Get a list of a directory's files and folders if certain critera are met.
  *
+ * @function readdirFilter
  * @param {String} dirPath The directory to read from
  * @param {Object} options Optional, filter options, see below
  * @param {String|RegExp|Array<String>|Array<RegExp>} options.include If given a string, return files that have that string as their extension. If given a Regular Expression, return the file that matches the pattern. Can also take a list of both. List matching behavior is described in `includeAll`.

src/readers/readdirFilterSync.js

@@ -3,6 +3,7 @@ import readdir from './readdir'
 /**
  * Synchronously get a list of a directory's files and folders if certain critera are met.
  *
+ * @function readdirFilterSync
  * @param {String} dirPath The directory to read from
  * @param {Object} [options] Optional, filter options, see below
  * @param {String|RegExp|Array<String>|Array<RegExp>} [options.include] Optional, if given a string, return files that have that string as their extension. If given a Regular Expression, return the file that matches the pattern. Can also take a list of both. List matching behavior is described in `includeAll`.

src/shorthandreaders/readAml.js

@@ -4,6 +4,7 @@ import parserAml from '../parsers/aml'
 /**
  * Asynchronously read an ArchieMl file. Returns an empty object if file is empty.
  *
+ * @function readAml
  * @param {String} fileName the name of the file.
  * @param {Function} [map] Optional map function. Takes the parsed filed, return modified file. See example below.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read.

src/shorthandreaders/readAmlSync.js

@@ -4,6 +4,7 @@ import parserAml from '../parsers/aml'
 /**
  * Synchronously read an ArchieML file. Returns an empty TK if file is empty.
  *
+ * @function readAmlSync
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function. Takes the parsed filed, return modified file. See example below.
  * @returns {Object} the contents of the file as a string

src/shorthandreaders/readCsv.js

@@ -4,6 +4,7 @@ import parserCsv from '../parsers/csv'
 /**
  * Asynchronously read a comma-separated value file. Returns an empty array if file is empty.
  *
+ * @function readCsv
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read

src/shorthandreaders/readCsvSync.js

@@ -4,6 +4,7 @@ import parserCsv from '../parsers/csv'
 /**
  * Synchronously read a comma-separated value file. Returns an empty array if file is empty.
  *
+ * @function readCsvSync
  * @param {String} fileName the name of the file
  * @param {Function|Object} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @returns {Array} the contents of the file as JSON

src/shorthandreaders/readJson.js

@@ -4,6 +4,7 @@ import parserJson from '../parsers/json'
 /**
  * Asynchronously read a JSON file. Returns an empty array if file is empty.
  *
+ * @function readJson
  * @param {String} fileName the name of the file
  * @param {Function|Object} [parserOptions] Can be a map function, or an object specifying other options.
  * @param {Function} [parserOptions.map] Optional map function, called once for each row (header row skipped). If your file is an array (tests if first non-whitespace character is a `[`), has signature `(row, i)`, delegates to `_.map`. If file is an object has signature `(value, key)`, delegates to `_.mapObject`. See example below.

src/shorthandreaders/readJsonSync.js

@@ -4,6 +4,7 @@ import parserJson from '../parsers/json'
 /**
  * Synchronously read a JSON file. Returns an empty array if file is empty.
  *
+ * @function readJsonSync
  * @param {String} fileName the name of the file
  * @param {Function|Object} [parserOptions] Can be a map function, or an object specifying other options.
  * @param {Function} [parserOptions.map] Optional map function, called once for each row (header row skipped). If your file is an array (tests if first non-whitespace character is a `[`), has signature `(row, i)`, delegates to `_.map`. If file is an object has signature `(value, key)`, delegates to `_.mapObject`. See example below.

src/shorthandreaders/readPsv.js

@@ -4,6 +4,7 @@ import parserPsv from '../parsers/psv'
 /**
  * Asynchronously read a pipe-separated value file. Returns an empty array if file is empty.
  *
+ * @function readPsv
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read

src/shorthandreaders/readPsvSync.js

@@ -4,6 +4,7 @@ import parserPsv from '../parsers/psv'
 /**
  * Synchronously read a pipe-separated value file. Returns an empty array if file is empty.
  *
+ * @function readPsvSync
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @returns {Array} the contents of the file as JSON

src/shorthandreaders/readTsv.js

@@ -4,6 +4,7 @@ import parserTsv from '../parsers/tsv'
 /**
  * Asynchronously read a tab-separated value file. Returns an empty array if file is empty.
  *
+ * @function readTsv
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read

src/shorthandreaders/readTsvSync.js

@@ -4,6 +4,7 @@ import parserTsv from '../parsers/tsv'
 /**
  * Synchronously read a tab-separated value file. Returns an empty array if file is empty.
  *
+ * @function readTsvSync
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @returns {Array} the contents of the file as JSON

src/shorthandreaders/readTxt.js

@@ -4,6 +4,7 @@ import parserTxt from '../parsers/txt'
 /**
  * Asynchronously read a text file. Returns an empty string if file is empty.
  *
+ * @function readTxt
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, take the file and returns any mapped value
  * @param {Function} callback callback used when read data is read, takes error (if any) and the data read

src/shorthandreaders/readTxtSync.js

@@ -4,6 +4,7 @@ import parserTxt from '../parsers/txt'
 /**
  * Synchronously read a text file. Returns an empty string if file is empty.
  *
+ * @function readTxtSync
  * @param {String} fileName the name of the file
  * @param {Function} [map] Optional map function, called once for each row (header row skipped). Has signature `(row, i, columns)`. See example below or d3-dsv documentation for details.
  * @returns {Array} the contents of the file as a string

src/shorthandreaders/readYaml.js

@@ -4,6 +4,7 @@ import parserYaml from '../parsers/yaml'
 /**
  * Asynchronously read a yaml file. Returns an empty object if file is empty. `parseOptions` will pass any other optinos directl to js-yaml library. See its documentation for more detail https://github.com/nodeca/js-yaml
  *
+ * @function readYaml
  * @param {String} fileName the name of the file
  * @param {Function|Object} [parserOptions] Can be a map function or an object specifying that or other options.
  * @param {Function} [parserOptions.map] Optional map function. Takes the parsed filed, return modified file. See example below.

src/shorthandreaders/readYamlSync.js

@@ -4,6 +4,7 @@ import parserYaml from '../parsers/yaml'
 /**
  * Synchronously read a yaml file. Returns an empty object if file is empty. `parseOptions` will pass any other optinos directl to js-yaml library. See its documentation for more detail https://github.com/nodeca/js-yaml
  *
+ * @function readYamlSync
  * @param {String} fileName the name of the file
  * @param {Function|Object} [parserOptions] Can be a map function or an object specifying that or other options.
  * @param {Function} [parserOptions.map] Optional map function. Takes the parsed filed, return modified file. See example below.

src/writers/appendData.js

@@ -18,6 +18,7 @@ import extend from '../helpers/extend'
  *
  * *Note: Does not currently support .dbf files.*
  *
+ * @function appendData
  * @param {String} fileName the name of the file
  * @param {Object} data the data to write
  * @param {Object} [options] Optional config object, see below

src/writers/appendDataSync.js

@@ -8,6 +8,7 @@ import extend from '../helpers/extend'
 /**
  * Synchronous version of {@link writers#appendData}. See that function for supported formats
  *
+ * @function appendDataSync
  * @param {String} fileName the name of the file
  * @param {Object} [options] Optional config object, see below
  * @param {Boolean} [options.makeDirectories=false] If true, create intermediate directories to your data file.

src/writers/writeData.js

@@ -16,6 +16,7 @@ import makeDirectories from '../helpers/makeDirectories'
  * * `.yaml` Yaml file, also supports `.yml`
  * * `.dbf` Database file, commonly used in ESRI-shapefile format.
  *
+ * @function writeData
  * @param {String} fileName the name of the file
  * @param {Object} data the data to write
  * @param {Object} [options] Optional config object, see below

src/writers/writeDataSync.js

@@ -9,6 +9,7 @@ import makeDirectoriesSync from '../helpers/makeDirectoriesSync'
  *
  * Supports the same formats with the exception of `.dbf` files
  *
+ * @function writeDataSync
  * @param {String} fileName the name of the file
  * @param {Object} [options] Optional config object, see below
  * @param {Boolean} [options.makeDirectories=false] If true, create intermediate directories to your data file.