Mirrors/lodash
1
0
Fork 0
mirror of https://github.com/whoisclebs/lodash.git synced 2026-02-04 00:57:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

fp docs - Inject default values and cap args.

Browse Source
This commit is contained in:
Jeroen Engels
2016-02-09 13:07:42 +01:00
committed by John-David Dalton
parent 5062f22839
commit 39735df82f
4 changed files with 526 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
lib/doc/test.js
View File

@@ -5,11 +5,12 @@ var Entry = require('docdown/lib/entry');
var applyFPMapping = require('./apply-fp-mapping');
var mapping = require('../../fp/_mapping');
function toExample(name, lines) {
function toSource(name, paramLines, exampleLines, attachedToPrototype) {
var start = [
"/**",
" * ",
" * @example"
" * Foo",
" * "
];
var end = [
" */",
@@ -17,16 +18,23 @@ function toExample(name, lines) {
"",
"}"
];
var example = lines.map(function(line) {
var staticLine = attachedToPrototype ? [] : [' * @static'];
var params = paramLines.map(function(line) {
return ' * @param ' + line;
});
var example = (exampleLines || []).map(function(line) {
return ' * ' + line;
});
return [].concat(start, example, end).join('\n');
return [].concat(start, staticLine, params, [' * @example'], example, end).join('\n');
}
function toParams(name, lines) {
function toParams(name, lines, wrapped) {
var start = [
"/**",
" * ",
" * Foo",
" * "
];
var end = [
" * @returns Foo bar",
@@ -35,12 +43,32 @@ function toParams(name, lines) {
"",
"}"
];
var example = lines.map(function(line) {
var staticLine = wrapped ? [] : [' * @static'];
var params = lines.map(function(line) {
return ' * @param ' + line;
});
return [].concat(start, example, end).join('\n');
return [].concat(start, staticLine, params, end).join('\n');
}
var differenceBySource = toSource('differenceBy', [
'{Array} array The array to inspect.',
'{...Array} [values] The values to exclude.',
'{Function|Object|string} [iteratee=_.identity] The iteratee invoked per element.'
], [
"_.differenceBy([3.1, 2.2, 1.3], [4.4, 2.5], Math.floor);",
"// → [3.1, 1.3]",
"",
"// The `_.property` iteratee shorthand.",
"_.differenceBy([{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }], 'x');",
"// → [{ 'x': 2 }]"
]);
var setParams = [
'{Object} object The object to modify.',
'{Array|string} path The path of the property to set.',
'{*} value The value to set.'
];
describe('Docs FP mapping', function() {
var oldgetParams;
var oldgetExample;
@@ -48,6 +76,7 @@ describe('Docs FP mapping', function() {
before(function() {
oldgetParams = Entry.prototype.getParams;
oldgetExample = Entry.prototype.getExample;
mapping.aryMethod[2].push('customFun');
applyFPMapping(mapping);
});
@@ -58,15 +87,7 @@ describe('Docs FP mapping', function() {
describe('getExample', function() {
it('should reorder parameters', function() {
var example = toExample('differenceBy', [
"_.differenceBy([3.1, 2.2, 1.3], [4.4, 2.5], Math.floor);",
"// → [3.1, 1.3]",
"",
"// The `_.property` iteratee shorthand.",
"_.differenceBy([{ 'x': 2 }, { 'x': 1 }], [{ 'x': 1 }], 'x');",
"// → [{ 'x': 2 }]"
]);
var entry = new Entry(example, example);
var entry = new Entry(differenceBySource, differenceBySource);
var actual = entry.getExample();
@@ -83,7 +104,7 @@ describe('Docs FP mapping', function() {
});
it('should reorder parameters that have a special order', function() {
var example = toExample('set', [
var example = toSource('set', setParams, [
"var object = { 'a': [{ 'b': { 'c': 3 } }] };",
"_.set(object, 'a[0].b.c', 4);",
"_.set(object, 'x[0].y.z', 5);",
@@ -102,7 +123,7 @@ describe('Docs FP mapping', function() {
});
it('should preserve comments', function() {
var example = toExample('set', [
var example = toSource('set', setParams, [
"var object = { 'a': [{ 'b': { 'c': 3 } }] };",
"_.set(object, 'a[0].b.c', 4);",
"// => 4",
@@ -123,7 +144,7 @@ describe('Docs FP mapping', function() {
});
it('should remove console.logs from example', function() {
var example = toExample('set', [
var example = toSource('set', setParams, [
"var object = { 'a': [{ 'b': { 'c': 3 } }] };",
"",
"_.set(object, 'a[0].b.c', 4);",
@@ -152,7 +173,11 @@ describe('Docs FP mapping', function() {
});
it('should merge extra arguments into an array', function() {
var example = toExample('pullAt', [
var example = toSource('pullAt', [
'{Array} array The array to modify.',
'{...(number|number[])} [indexes] The indexes of elements to remove,\n' +
' * specified individually or in arrays.'
], [
"var array = [5, 10, 15, 20];",
"var evens = _.pullAt(array, 1, 3);",
"",
@@ -177,10 +202,139 @@ describe('Docs FP mapping', function() {
"```"
].join('\n'));
});
it('should inject default values into optional arguments that became compulsory', function() {
var example = toSource('sampleSize', [
'{Array|Object} collection The collection to sample.',
'{number} [n=0] The number of elements to sample.'
], [
"_.sampleSize([1, 2, 3]);",
"// => [3, 1]",
"",
"_.sampleSize([1, 2, 3], 4);",
"// => [2, 3, 1]"
]);
var entry = new Entry(example, example);
var actual = entry.getExample();
assert.equal(actual, [
"```js",
"_.sampleSize(0, [1, 2, 3]);",
"// => [3, 1]",
"",
"_.sampleSize(4, [1, 2, 3]);",
"// => [2, 3, 1]",
"```"
].join('\n'));
});
it('should inject referenced values into optional arguments that became compulsory, '
+ 'if a parameter\'s default value references parameter (direct reference)',
function() {
var example = toSource('customFun', [
'{Array} array Array',
'{number} [foo=array] Foo'
], [
"_.customFun([1, 2, 3]);",
]);
var entry = new Entry(example, example);
var actual = entry.getExample();
assert.equal(actual, [
"```js",
"_.customFun([1, 2, 3], [1, 2, 3]);",
"```"
].join('\n'));
});
it('should inject referenced values into optional arguments that became compulsory, '
+ 'if a parameter\'s default value references parameter (member expression)',
function() {
var example = toSource('fill', [
'{Array} array The array to fill.',
'{*} value The value to fill `array` with.',
'{number} [start=0] The start position.',
'{number} [end=array.length] The end position.'
], [
"var array = [1, 2, 3];",
"",
"_.fill(array, 'a');",
"console.log(array);",
"// => ['a', 'a', 'a']",
"",
"_.fill(Array(3), 2, 1);",
"// => [undefined, 2, 2]",
"",
"_.fill([4, 6, 8, 10], '*');",
"// => [*, '*', '*', *]"
]);
var entry = new Entry(example, example);
var actual = entry.getExample();
assert.equal(actual, [
"```js",
"var array = [1, 2, 3];",
"",
"_.fill(0, array.length, 'a', array);",
"// => ['a', 'a', 'a']",
"",
"_.fill(1, 3, 2, Array(3));",
"// => [undefined, 2, 2]",
"",
"_.fill(0, 4, '*', [4, 6, 8, 10]);",
"// => [*, '*', '*', *]",
"```"
].join('\n'));
});
it('should inject default values in the middle of the arguments', function() {
var example = toSource('inRange', [
'{number} number The number to check.',
'{number} [start=0] The start of the range.',
'{number} end The end of the range.'
], [
"_.inRange(4, 8);",
"// => true"
]);
var entry = new Entry(example, example);
var actual = entry.getExample();
assert.equal(actual, [
"```js",
"_.inRange(8, 0, 4);",
"// => true",
"```"
].join('\n'));
});
it('should not use ignored params as default values', function() {
var example = toSource('drop', [
'{Array} array The array to query.',
'{number} [n=1] The number of elements to drop.',
'{Object} [guard] Enables use as an iteratee for functions like `_.map`.'
], [
"_.drop([1, 2, 3]);",
"// => [2, 3]"
]);
var entry = new Entry(example, example);
var actual = entry.getExample();
assert.equal(actual, [
"```js",
"_.drop(1, [1, 2, 3]);",
"// => [2, 3]",
"```"
].join('\n'));
});
});
describe('getParams', function() {
it('should reorder arguments', function() {
it('should reorder arguments and remove default values', function() {
var example = toParams('differenceBy', [
'{Array} array The array to inspect.',
'{...Array} [values] The values to exclude.',
@@ -191,8 +345,8 @@ describe('Docs FP mapping', function() {
var actual = entry.getParams();
assert.deepEqual(actual, [
['Function|Object|string', '[iteratee=_.identity]', 'The iteratee invoked per element. '],
['Array|Array[]', '[values]', 'The values to exclude. '],
['Function|Object|string', 'iteratee', 'The iteratee invoked per element. '],
['Array|Array[]', 'values', 'The values to exclude. '],
['Array', 'array', 'The array to inspect. ']
]);
});
@@ -228,10 +382,57 @@ describe('Docs FP mapping', function() {
// TODO Remove this line in favor of the commented one.
// Is linked to a docdown (https://github.com/jdalton/docdown/pull/37)
// that does not handle parens in the arguments well
['((number|number)|((number|number)[]', '[indexes]', 'The indexes of elements to remove, specified individually or in arrays. '],
['((number|number)|((number|number)[]', 'indexes', 'The indexes of elements to remove, specified individually or in arrays. '],
// ['number|number[]', '[indexes]', 'The indexes of elements to remove, specified individually or in arrays. '],
['Array', 'array', 'The array to modify. '],
]);
});
});
it('should duplicate and de-restify "rest" parameters if there are less parameters than cap', function() {
var example = toParams('intersectionWith', [
'{...Array} [arrays] The arrays to inspect.',
'{Function} [comparator] The comparator invoked per element.'
]);
var entry = new Entry(example, example);
var actual = entry.getParams();
assert.deepEqual(actual, [
['Function', 'comparator', 'The comparator invoked per element. '],
['Array', 'arrays', 'The arrays to inspect. '],
['Array', 'arrays', 'The arrays to inspect. ']
]);
});
it('should consider method to have an ary of `ary - 1` when capped and wrapped', function() {
var wrapped = true;
var example = toParams('flatMap', [
'{Array} array The array to iterate over.',
'{Function|Object|string} [iteratee=_.identity] The function invoked per iteration.'
], wrapped);
var entry = new Entry(example, example);
var actual = entry.getParams();
assert.deepEqual(actual, [
['Function|Object|string', 'iteratee', 'The function invoked per iteration. ']
]);
});
it('should remove arguments ignored because of capping', function() {
var example = toParams('includes', [
'{Array|Object|string} collection The collection to search.',
'{*} value The value to search for.',
'{number} [fromIndex=0] The index to search from.'
]);
var entry = new Entry(example, example);
var actual = entry.getParams();
assert.deepEqual(actual, [
['*', 'value', 'The value to search for. '],
['Array|Object|string', 'collection', 'The collection to search. ']
]);
});
});