From 0da3674d5e9418cd0e51ce7ccfc895224c2a2edd Mon Sep 17 00:00:00 2001
From: John-David Dalton <john.david.dalton@gmail.com>
Date: Mon, 15 Feb 2016 17:00:01 -0800
Subject: [PATCH] Update fp doc template.

---
 lib/fp/build-doc.js          | 33 ++++++++++----
 lib/fp/template/doc/wiki.jst | 84 ++++++++++++++++++++++++++++++------
 2 files changed, 96 insertions(+), 21 deletions(-)

diff --git a/lib/fp/build-doc.js b/lib/fp/build-doc.js
index b67c88132..bba62d2e6 100644
--- a/lib/fp/build-doc.js
+++ b/lib/fp/build-doc.js
@@ -5,29 +5,45 @@ var _ = require('lodash'),
     path = require('path'),
     util = require('../common/util');
 
-var basePath = path.join(__dirname, '..', '..'),
-    docPath = path.join(basePath, 'doc'),
-    readmePath = path.join(docPath, 'FP-Guide.md');
-
 var mapping = require('../../fp/_mapping'),
     templatePath = path.join(__dirname, 'template/doc'),
     template = util.globTemplate(path.join(templatePath, '*.jst'));
 
+var argNames = ['a', 'b', 'c', 'd'];
+
 var templateData = {
   'mapping': mapping,
+  'toArgOrder': toArgOrder,
   'toFuncList': toFuncList
 };
 
+function toArgOrder(array) {
+  return '`(' + _.map(array, function(value) {
+    return argNames[value];
+  }).join(', ') + ')`';
+}
+
 function toFuncList(array) {
   var chunks = _.chunk(array.slice().sort(), 5),
       lastChunk = _.last(chunks),
       last = lastChunk ? lastChunk.pop() : undefined;
 
+  chunks = _.reject(chunks, _.isEmpty);
+  lastChunk = _.last(chunks);
+
   var result = '`' + _.map(chunks, function(chunk) {
     return chunk.join('`, `') + '`';
   }).join(',\n`');
 
-  return result + (last == null ? '' : (', & `' + last + '`'));
+  if (last == null) {
+    return result;
+  }
+  if (_.size(chunks) > 1 || _.size(lastChunk) > 1) {
+    result += ',';
+  }
+  result += ' &';
+  result += _.size(lastChunk) < 5 ? ' ' : '\n';
+  return result + '`' + last + '`';
 }
 
 /*----------------------------------------------------------------------------*/
@@ -38,8 +54,9 @@ function onComplete(error) {
   }
 }
 
-function build() {
-  fs.writeFile(readmePath, template.wiki(templateData), onComplete);
+function build(target) {
+  target = path.resolve(target);
+  fs.writeFile(target, template.wiki(templateData), onComplete);
 }
 
-build();
+build(_.last(process.argv));
diff --git a/lib/fp/template/doc/wiki.jst b/lib/fp/template/doc/wiki.jst
index 6cc54e554..abb7456bd 100644
--- a/lib/fp/template/doc/wiki.jst
+++ b/lib/fp/template/doc/wiki.jst
@@ -1,7 +1,7 @@
 ## lodash/fp
 
-The lodash/fp module is an instance of lodash with its methods wrapped to produce
-immutable auto-curried iteratee-first data-last methods.
+The `lodash/fp` module is an instance of `lodash` with its methods wrapped to
+produce immutable auto-curried iteratee-first data-last methods.
 
 ## Installation
 
@@ -13,30 +13,74 @@ In a browser:
 
 In Node.js:
 ```js
-// load the fp build
+// Load the fp build.
 var _ = require('lodash/fp');
 
-// or a method category
-var array = require('lodash/fp/object');
+// Load a method category.
+var object = require('lodash/fp/object');
 
-// or method for smaller builds with browserify/rollup/webpack
+// Load a single method for smaller builds with browserify/rollup/webpack.
 var extend = require('lodash/fp/extend');
 ```
 
+## Convert
+
+This module is used to convert Lodash methods into their `fp` counterparts.
+```js
+var convert = require('lodash/fp/convert');
+
+// Convert by name.
+var assign = convert('assign', require('lodash.assign'));
+
+// Convert by object.
+var fp = convert({
+  'assign': require('lodash.assign'),
+  'chunk': require('lodash.chunk')
+});
+
+// Convert by `lodash` instance.
+var fp = convert(lodash.runInContext());
+```
+
+It’s customizable to create the `fp` wrapper that’s right for you.
+```js
+// Every option is `true` by default.
+var filter = convert('filter', _.filter, {
+  // Specify capping iteratee arguments.
+  'cap': true,
+  // Specify currying.
+  'curry': true,
+  // Specify fixed arity.
+  'fixed': true,
+  // Specify immutable operations.
+  'immutable': true,
+  // Specify rearranging arguments.
+  'rearg': true
+});
+
+// Set `cap` to `false` to create a wrapper that doesn’t cap iteratee arguments.
+var filter = convert('filter', _.filter, { 'cap': false });
+
+filter(function(value, index) {
+  return index % 2 == 0;
+})(['a', 'b', 'c']);
+// => ['a', 'c']
+```
+
 ## Notes
 
 #### Arity
 
-Methods with arity capped to one argument:<br>
+Methods with arity fixed to one argument:<br>
 <%= toFuncList(mapping.aryMethod[1]) %>
 
-Methods with arity capped to two arguments:<br>
+Methods with arity fixed to two arguments:<br>
 <%= toFuncList(mapping.aryMethod[2]) %>
 
-Methods with arity capped to three arguments:<br>
+Methods with arity fixed to three arguments:<br>
 <%= toFuncList(mapping.aryMethod[3]) %>
 
-Methods with arity capped to four arguments:<br>
+Methods with arity fixed to four arguments:<br>
 <%= toFuncList(mapping.aryMethod[4]) %>
 
 #### Iteratees
@@ -52,14 +96,28 @@ Methods which provide iteratees two argument:<br>
 Methods created to accommodate Lodash’s variadic methods:<br>
 <%= toFuncList(_.keys(mapping.remap)) %>
 
-#### Exceptions
+#### Argument Orders
 
-Methods which have argument order unchanged:<br>
+Methods fixed to two arguments have an argument order of<br>
+<%= toArgOrder(mapping.aryRearg[2]) %>
+
+Methods fixed to three arguments have an argument order of<br>
+<%= toArgOrder(mapping.aryRearg[3]) %>
+
+Methods fixed to four arguments have an argument order of<br>
+<%= toArgOrder(mapping.aryRearg[4]) %>
+
+Methods with custom argument orders:<br>
+<%= _.map(mapping.methodRearg, function(orders, methodName) {
+  return ' * `_.' + methodName + '` has an order of ' + toArgOrder(orders);
+}).join('\n') %>
+
+Methods with unchanged argument orders:<br>
 <%= toFuncList(_.keys(mapping.skipRearg)) %>
 
 #### Aliases
 
 There are <%= _.size(mapping.aliasToReal) %> method aliases:<br>
 <%= _.map(mapping.aliasToReal, function(realName, alias) {
-  return ' - Added `_.' + alias + '` as an alias of `_.' + realName + '`';
+  return ' * Added `_.' + alias + '` as an alias of `_.' + realName + '`';
 }).join('\n') %>