adds-symbols - initial commit (#1852)

* adds-symbols - initial commit

* fix lint error: trailing spaces in mapAccum.js and mapAccumRight.js

src/adjust.js

@@ -24,6 +24,8 @@ var _curry3 = require('./internal/_curry3');
  *
  *      R.adjust(R.add(10), 1, [0, 1, 2]);     //=> [0, 11, 2]
  *      R.adjust(R.add(10))(1)([0, 1, 2]);     //=> [0, 11, 2]
+ * @symb R.adjust(f, -1, [a, b]) = [a, f(b)]
+ * @symb R.adjust(f, 0, [a, b]) = [f(a), b]
  */
 module.exports = _curry3(function adjust(fn, idx, list) {
   if (idx >= list.length || idx < -list.length) {

src/ap.js

@@ -22,6 +22,7 @@ var map = require('./map');
  * @example
  *
  *      R.ap([R.multiply(2), R.add(3)], [1,2,3]); //=> [2, 4, 6, 4, 5, 6]
+ * @symb R.ap([f, g], [a, b]) = [f(a), f(b), g(a), g(b)]
  */
 module.exports = _curry2(function ap(applicative, fn) {
   return (

src/apply.js

@@ -19,6 +19,7 @@ var _curry2 = require('./internal/_curry2');
  *
  *      var nums = [1, 2, 3, -99, 42, 6, 7];
  *      R.apply(Math.max, nums); //=> 42
+ * @symb R.apply(f, [a, b, c]) = f(a, b, c)
  */
 module.exports = _curry2(function apply(fn, args) {
   return fn.apply(this, args);

src/applySpec.js

@@ -31,6 +31,7 @@ var values = require('./values');
  *                                      nested: { mul: R.multiply }
  *                                   });
  *      getMetrics(2, 4); // => { sum: 6, nested: { mul: 8 } }
+ * @symb R.applySpec({ x: f, y: { z: g } })(a, b) = { x: f(a, b), y: { z: g(a, b) } }
  */
 module.exports = _curry1(function applySpec(spec) {
   spec = map(function(v) { return typeof v == 'function' ? v : applySpec(v) },

src/binary.js

@@ -27,6 +27,7 @@ var nAry = require('./nAry');
  *      takesTwoArgs.length; //=> 2
  *      // Only 2 arguments are passed to the wrapped function
  *      takesTwoArgs(1, 2, 3); //=> [1, 2, undefined]
+ * @symb R.binary(f)(a, b, c) = f(a, b)
  */
 module.exports = _curry1(function binary(fn) {
   return nAry(2, fn);

src/bind.js

@@ -22,6 +22,7 @@ var _curry2 = require('./internal/_curry2');
  *      var log = R.bind(console.log, console);
  *      R.pipe(R.assoc('a', 2), R.tap(log), R.assoc('a', 3))({a: 1}); //=> {a: 3}
  *      // logs {a: 2}
+ * @symb R.bind(f, o)(a, b) = f.call(o, a, b)
  */
 module.exports = _curry2(function bind(fn, thisObj) {
   return _arity(fn.length, function() {

src/call.js

@@ -29,6 +29,7 @@ var curry = require('./curry');
  *                              ]);
  *
  *      format({indent: 2, value: 'foo\nbar\nbaz\n'}); //=> '  foo\n  bar\n  baz\n'
+ * @symb R.call(f, a, b) = f(a, b)
  */
 module.exports = curry(function call(fn) {
   return fn.apply(this, _slice(arguments, 1));

src/compose.js

@@ -21,6 +21,7 @@ var reverse = require('./reverse');
  *      var f = R.compose(R.inc, R.negate, Math.pow);
  *
  *      f(3, 4); // -(3^4) + 1
+ * @symb R.compose(f, g, h)(a, b) = f(g(h(a, b)))
  */
 module.exports = function compose() {
   if (arguments.length === 0) {

src/composeK.js

@@ -37,6 +37,7 @@ var prepend = require('./prepend');
  *      //=> Just('NY')
  *      getStateCode(Maybe.of('[Invalid JSON]'));
  *      //=> Nothing()
+ * @symb R.composeK(f, g, h)(a, b) = R.chain(f, R.chain(g, h(a, b)))
  */
 module.exports = function composeK() {
   return compose.apply(this, prepend(identity, map(chain, arguments)));

src/converge.js

@@ -33,6 +33,7 @@ var reduce = require('./reduce');
  *
  *      var add3 = (a, b, c) => a + b + c;
  *      R.converge(add3, [multiply, add, subtract])(1, 2); //=> 4
+ * @symb R.converge(f, [g, h])(a, b) = f(g(a, b), h(a, b))
  */
 module.exports = _curry2(function converge(after, fns) {
   return curryN(reduce(max, 0, pluck('length', fns)), function() {

src/flip.js

@@ -21,6 +21,7 @@ var curry = require('./curry');
  *      mergeThree(1, 2, 3); //=> [1, 2, 3]
  *
  *      R.flip(mergeThree)(1, 2, 3); //=> [2, 1, 3]
+ * @symb R.flip(f)(a, b, c) = f(b, a, c)
  */
 module.exports = _curry1(function flip(fn) {
   return curry(function(a, b) {

src/forEach.js

@@ -34,6 +34,7 @@ var _curry2 = require('./internal/_curry2');
  *      // logs 6
  *      // logs 7
  *      // logs 8
+ * @symb R.forEach(f, [a, b, c]) = [a, b, c]
  */
 module.exports = _curry2(_checkForMethod('forEach', function forEach(fn, list) {
   var len = list.length;

src/identity.js

@@ -19,5 +19,6 @@ var _identity = require('./internal/_identity');
  *
  *      var obj = {};
  *      R.identity(obj) === obj; //=> true
+ * @symb R.identity(a) = a
  */
 module.exports = _curry1(_identity);

src/invoker.js

@@ -27,6 +27,9 @@ var toString = require('./toString');
  *      sliceFrom(6, 'abcdefghijklm'); //=> 'ghijklm'
  *      var sliceFrom6 = R.invoker(2, 'slice')(6);
  *      sliceFrom6(8, 'abcdefghijklm'); //=> 'gh'
+ * @symb R.invoker(0, 'method')(o) = o['method']()
+ * @symb R.invoker(1, 'method')(a, o) = o['method'](a)
+ * @symb R.invoker(2, 'method')(a, b, o) = o['method'](a, b)
  */
 module.exports = _curry2(function invoker(arity, method) {
   return curryN(arity + 1, function() {

src/juxt.js

@@ -18,6 +18,7 @@ var converge = require('./converge');
  *
  *      var getRange = R.juxt([Math.min, Math.max]);
  *      getRange(3, 4, 9, -3); //=> [-3, 9]
+ * @symb R.juxt([f, g, h])(a, b) = [f(a, b), g(a, b), h(a, b)]
  */
 module.exports = _curry1(function juxt(fns) {
   return converge(_arrayOf, fns);

src/map.js

@@ -38,6 +38,9 @@ var keys = require('./keys');
  *      R.map(double, [1, 2, 3]); //=> [2, 4, 6]
  *
  *      R.map(double, {x: 1, y: 2, z: 3}); //=> {x: 2, y: 4, z: 6}
+ * @symb R.map(f, [a, b]) = [f(a), f(b)]
+ * @symb R.map(f, { x: a, y: b }) = { x: f(a), y: f(b) }
+ * @symb R.map(f, functor_o) = functor_o.map(f)
  */
 module.exports = _curry2(_dispatchable('map', _xmap, function map(fn, functor) {
   switch (Object.prototype.toString.call(functor)) {

src/mapAccum.js

@@ -26,6 +26,14 @@ var _curry3 = require('./internal/_curry3');
  *      var appender = (a, b) => [a + b, a + b];
  *
  *      R.mapAccum(appender, 0, digits); //=> ['01234', ['01', '012', '0123', '01234']]
+ * @symb R.mapAccum(f, a, [b, c, d]) = [
+ *   f(f(f(a, b)[0], c)[0], d)[0],
+ *   [
+ *     f(a, b)[1],
+ *     f(f(a, b)[0], c)[1],
+ *     f(f(f(a, b)[0], c)[0], d)[1]
+ *   ]
+ * ]
  */
 module.exports = _curry3(function mapAccum(fn, acc, list) {
   var idx = 0;

src/mapAccumRight.js

@@ -29,6 +29,14 @@ var _curry3 = require('./internal/_curry3');
  *      var append = (a, b) => [a + b, a + b];
  *
  *      R.mapAccumRight(append, 0, digits); //=> ['04321', ['04321', '0432', '043', '04']]
+ * @symb R.mapAccumRight(f, a, [b, c, d]) = [
+ *   f(f(f(a, d)[0], c)[0], b)[0],
+ *   [
+ *     f(a, d)[1],
+ *     f(f(a, d)[0], c)[1],
+ *     f(f(f(a, d)[0], c)[0], b)[1]
+ *   ]
+ * ]
  */
 module.exports = _curry3(function mapAccumRight(fn, acc, list) {
   var idx = list.length - 1;

src/merge.js

@@ -23,6 +23,7 @@ var _curry2 = require('./internal/_curry2');
  *
  *      var resetToDefault = R.merge(R.__, {x: 0});
  *      resetToDefault({x: 5, y: 2}); //=> {x: 0, y: 2}
+ * @symb R.merge({ x: 1, y: 2 }, { y: 5, z: 3 }) = { x: 1, y: 5, z: 3 }
  */
 module.exports = _curry2(function merge(l, r) {
   return _assign({}, l, r);

src/mergeAll.js

@@ -17,6 +17,7 @@ var _curry1 = require('./internal/_curry1');
  *
  *      R.mergeAll([{foo:1},{bar:2},{baz:3}]); //=> {foo:1,bar:2,baz:3}
  *      R.mergeAll([{foo:1},{foo:2},{bar:2}]); //=> {foo:2,bar:2}
+ * @symb R.mergeAll([{ x: 1 }, { y: 2 }, { z: 3 }]) = { x: 1, y: 2, z: 3 }
  */
 module.exports = _curry1(function mergeAll(list) {
   return _assign.apply(null, [{}].concat(list));

src/mergeWithKey.js

@@ -27,6 +27,7 @@ var _has = require('./internal/_has');
  *                     { a: true, thing: 'foo', values: [10, 20] },
  *                     { b: true, thing: 'bar', values: [15, 35] });
  *      //=> { a: true, b: true, thing: 'bar', values: [10, 20, 15, 35] }
+ * @symb R.mergeWithKey(f, { x: 1, y: 2 }, { y: 5, z: 3 }) = { x: 1, y: f('y', 2, 5), z: 3 }
  */
 module.exports = _curry3(function mergeWithKey(fn, l, r) {
   var result = {};

src/nAry.js

@@ -26,6 +26,9 @@ var _curry2 = require('./internal/_curry2');
  *      takesOneArg.length; //=> 1
  *      // Only `n` arguments are passed to the wrapped function
  *      takesOneArg(1, 2); //=> [1, undefined]
+ * @symb R.nAry(0, f)(a, b) = f()
+ * @symb R.nAry(1, f)(a, b) = f(a)
+ * @symb R.nAry(2, f)(a, b) = f(a, b)
  */
 module.exports = _curry2(function nAry(n, fn) {
   switch (n) {

src/nth.js

@@ -24,6 +24,9 @@ var _isString = require('./internal/_isString');
  *
  *      R.nth(2, 'abc'); //=> 'c'
  *      R.nth(3, 'abc'); //=> ''
+ * @symb R.nth(-1, [a, b, c]) = c
+ * @symb R.nth(0, [a, b, c]) = a
+ * @symb R.nth(1, [a, b, c]) = b
  */
 module.exports = _curry2(function nth(offset, list) {
   var idx = offset < 0 ? list.length + offset : offset;

src/nthArg.js

@@ -17,6 +17,9 @@ var nth = require('./nth');
  *
  *      R.nthArg(1)('a', 'b', 'c'); //=> 'b'
  *      R.nthArg(-1)('a', 'b', 'c'); //=> 'c'
+ * @symb R.nthArg(-1)(a, b, c) = c
+ * @symb R.nthArg(0)(a, b, c) = a
+ * @symb R.nthArg(1)(a, b, c) = b
  */
 module.exports = _curry1(function nthArg(n) {
   var arity = n < 0 ? 1 : n + 1;

src/partial.js

@@ -28,5 +28,6 @@ var _createPartialApplicator = require('./internal/_createPartialApplicator');
  *      var sayHello = R.partial(greet, ['Hello']);
  *      var sayHelloToMs = R.partial(sayHello, ['Ms.']);
  *      sayHelloToMs('Jane', 'Jones'); //=> 'Hello, Ms. Jane Jones!'
+ * @symb R.partial(f, [a, b])(c, d) = f(a, b, c, d)
  */
 module.exports = _createPartialApplicator(_concat);

src/partialRight.js

@@ -25,5 +25,6 @@ var flip = require('./flip');
  *      var greetMsJaneJones = R.partialRight(greet, ['Ms.', 'Jane', 'Jones']);
  *
  *      greetMsJaneJones('Hello'); //=> 'Hello, Ms. Jane Jones!'
+ * @symb R.partialRight(f, [a, b])(c, d) = f(c, d, a, b)
  */
 module.exports = _createPartialApplicator(flip(_concat));

src/pipe.js

@@ -25,6 +25,7 @@ var tail = require('./tail');
  *      var f = R.pipe(Math.pow, R.negate, R.inc);
  *
  *      f(3, 4); // -(3^4) + 1
+ * @symb R.pipe(f, g, h)(a, b) = h(g(f(a, b)))
  */
 module.exports = function pipe() {
   if (arguments.length === 0) {

src/pipeK.js

@@ -33,6 +33,7 @@ var reverse = require('./reverse');
  *      //=> Just('NY')
  *      getStateCode(Maybe.of('[Invalid JSON]'));
  *      //=> Nothing()
+ * @symb R.pipeK(f, g, h)(a, b) = R.chain(h, R.chain(g, f(a, b)))
  */
 module.exports = function pipeK() {
   return composeK.apply(this, reverse(arguments));

src/pluck.js

@@ -20,6 +20,8 @@ var prop = require('./prop');
  *
  *      R.pluck('a')([{a: 1}, {a: 2}]); //=> [1, 2]
  *      R.pluck(0)([[1, 2], [3, 4]]);   //=> [1, 3]
+ * @symb R.pluck('x', [{x: 1, y: 2}, {x: 3, y: 4}, {x: 5, y: 6}]) = [1, 3, 5]
+ * @symb R.pluck(0, [[1, 2], [3, 4], [5, 6]]) = [1, 3, 5]
  */
 module.exports = _curry2(function pluck(p, list) {
   return map(prop(p), list);

src/reduce.js

@@ -34,5 +34,6 @@ var _reduce = require('./internal/_reduce');
  *      var plus = (a, b) => a + b;
  *
  *      R.reduce(plus, 10, numbers); //=> 16
+ * @symb R.reduce(f, a, [b, c, d]) = f(f(f(a, b), c), d)
  */
 module.exports = _curry3(_reduce);

src/repeat.js

@@ -21,6 +21,9 @@ var times = require('./times');
  *      var obj = {};
  *      var repeatedObjs = R.repeat(obj, 5); //=> [{}, {}, {}, {}, {}]
  *      repeatedObjs[0] === repeatedObjs[1]; //=> true
+ * @symb R.repeat(a, 0) = []
+ * @symb R.repeat(a, 1) = [a]
+ * @symb R.repeat(a, 2) = [a, a]
  */
 module.exports = _curry2(function repeat(value, n) {
   return times(always(value), n);

src/scan.js

@@ -19,6 +19,7 @@ var _curry3 = require('./internal/_curry3');
  *
  *      var numbers = [1, 2, 3, 4];
  *      var factorials = R.scan(R.multiply, 1, numbers); //=> [1, 1, 2, 6, 24]
+ * @symb R.scan(f, a, [b, c]) = [a, f(a, b), f(f(a, b), c)]
  */
 module.exports = _curry3(function scan(fn, acc, list) {
   var idx = 0;

src/take.js

@@ -42,6 +42,10 @@ var slice = require('./slice');
  *      var takeFive = R.take(5);
  *      takeFive(personnel);
  *      //=> ['Dave Brubeck', 'Paul Desmond', 'Eugene Wright', 'Joe Morello', 'Gerry Mulligan']
+ * @symb R.take(-1, [a, b]) = [a, b]
+ * @symb R.take(0, [a, b]) = []
+ * @symb R.take(1, [a, b]) = [a]
+ * @symb R.take(2, [a, b]) = [a, b]
  */
 module.exports = _curry2(_dispatchable('take', _xtake, function take(n, xs) {
   return slice(0, n < 0 ? Infinity : n, xs);

src/tap.js

@@ -17,6 +17,7 @@ var _curry2 = require('./internal/_curry2');
  *      var sayX = x => console.log('x is ' + x);
  *      R.tap(sayX, 100); //=> 100
  *      // logs 'x is 100'
+ * @symb R.tap(f, a) = a
  */
 module.exports = _curry2(function tap(fn, x) {
   fn(x);

src/times.js

@@ -19,6 +19,9 @@ var _curry2 = require('./internal/_curry2');
  * @example
  *
  *      R.times(R.identity, 5); //=> [0, 1, 2, 3, 4]
+ * @symb R.times(f, 0) = []
+ * @symb R.times(f, 1) = [f(0)]
+ * @symb R.times(f, 2) = [f(0), f(1)]
  */
 module.exports = _curry2(function times(fn, n) {
   var len = Number(n);

src/transpose.js

@@ -22,6 +22,9 @@ var _curry1 = require('./internal/_curry1');
  * If some of the rows are shorter than the following rows, their elements are skipped:
  *
  *      R.transpose([[10, 11], [20], [], [30, 31, 32]]) //=> [[10, 20, 30], [11, 31], [32]]
+ * @symb R.transpose([[a], [b], [c]]) = [a, b, c]
+ * @symb R.transpose([[a, b], [c, d]]) = [[a, c], [b, d]]
+ * @symb R.transpose([[a, b], [c]]) = [[a, c], [b]]
  */
 module.exports = _curry1(function transpose(outerlist) {
   var i = 0;

src/unapply.js

@@ -24,6 +24,7 @@ var _slice = require('./internal/_slice');
  * @example
  *
  *      R.unapply(JSON.stringify)(1, 2, 3); //=> '[1,2,3]'
+ * @symb R.unapply(f)(a, b) = f([a, b])
  */
 module.exports = _curry1(function unapply(fn) {
   return function() {

src/unary.js

@@ -27,6 +27,7 @@ var nAry = require('./nAry');
  *      takesOneArg.length; //=> 1
  *      // Only 1 argument is passed to the wrapped function
  *      takesOneArg(1, 2); //=> [1, undefined]
+ * @symb R.unary(f)(a, b, c) = f(a)
  */
 module.exports = _curry1(function unary(fn) {
   return nAry(1, fn);

src/unfold.js

@@ -24,6 +24,7 @@ var _curry2 = require('./internal/_curry2');
  *
  *      var f = n => n > 50 ? false : [-n, n + 10];
  *      R.unfold(f, 10); //=> [-10, -20, -30, -40, -50]
+ * @symb R.unfold(f, x) = [f(x)[0], f(f(x)[1])[0], f(f(f(x)[1])[1])[0], ...]
  */
 module.exports = _curry2(function unfold(fn, seed) {
   var pair = fn(seed);

src/update.js

@@ -21,6 +21,9 @@ var always = require('./always');
  *
  *      R.update(1, 11, [0, 1, 2]);     //=> [0, 11, 2]
  *      R.update(1)(11)([0, 1, 2]);     //=> [0, 11, 2]
+ * @symb R.update(-1, a, [b, c]) = [b, a]
+ * @symb R.update(0, a, [b, c]) = [a, c]
+ * @symb R.update(1, a, [b, c]) = [b, a]
  */
 module.exports = _curry3(function update(idx, x, list) {
   return adjust(always(x), idx, list);

src/useWith.js

@@ -29,6 +29,7 @@ var curryN = require('./curryN');
  *      R.useWith(Math.pow, [R.identity, R.identity])(3)(4); //=> 81
  *      R.useWith(Math.pow, [R.dec, R.inc])(3, 4); //=> 32
  *      R.useWith(Math.pow, [R.dec, R.inc])(3)(4); //=> 32
+ * @symb R.useWith(f, [g, h])(a, b) = f(g(a), h(b))
  */
 module.exports = _curry2(function useWith(fn, transformers) {
   return curryN(transformers.length, function() {

src/xprod.js

@@ -17,6 +17,7 @@ var _curry2 = require('./internal/_curry2');
  * @example
  *
  *      R.xprod([1, 2], ['a', 'b']); //=> [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+ * @symb R.xprod([a, b], [c, d]) = [[a, c], [a, d], [b, c], [b, d]]
  */
 module.exports = _curry2(function xprod(a, b) { // = xprodWith(prepend); (takes about 3 times as long...)
   var idx = 0;

src/zip.js

@@ -18,6 +18,7 @@ var _curry2 = require('./internal/_curry2');
  * @example
  *
  *      R.zip([1, 2, 3], ['a', 'b', 'c']); //=> [[1, 'a'], [2, 'b'], [3, 'c']]
+ * @symb R.zip([a, b, c], [d, e, f]) = [[a, d], [b, e], [c, f]]
  */
 module.exports = _curry2(function zip(a, b) {
   var rv = [];

src/zipWith.js

@@ -23,6 +23,7 @@ var _curry3 = require('./internal/_curry3');
  *      };
  *      R.zipWith(f, [1, 2, 3], ['a', 'b', 'c']);
  *      //=> [f(1, 'a'), f(2, 'b'), f(3, 'c')]
+ * @symb R.zipWith(fn, [a, b, c], [d, e, f]) = [fn(a, d), fn(b, e), fn(c, f)]
  */
 module.exports = _curry3(function zipWith(fn, a, b) {
   var rv = [];