diff options
| -rw-r--r-- | API.md | 60 | ||||
| -rw-r--r-- | HISTORY.md | 4 | ||||
| -rw-r--r-- | README.md | 84 | ||||
| -rw-r--r-- | package.json | 4 |
4 files changed, 73 insertions, 79 deletions
@@ -0,0 +1,60 @@ +#Index + +**Functions** + +* [once(id)](#once) +* [removeOnce(id)](#removeOnce) +* [findOnce(id)](#findOnce) + +<a name="once"></a> +#once(id) +Filter elements by whether they have not yet been processed. + +**Params** + +- id `string` - The data id used to determine whether the given elements have already + been processed or not. + +**Returns**: - jQuery element collection of elements that have now run once by + the given id. +**Example** +// Change the color to green only once. +$('p').once('changecolor').css('color', 'green'); + +<a name="removeOnce"></a> +#removeOnce(id) +Removes the once data from the given elements, based on the given ID. + +**Params** + +- id `string` - A required string representing the name of the data id which should be used + when filtering the elements. This only filters elements that have already + been processed by the once function. The id should be the same id that + was originally passed to the once() function. + +**Returns**: - jQuery element collection of elements that now have their once + data removed. +**Example** +// Remove once data with the "changecolor" ID. +$('p').removeOnce('changecolor').each(function() { + // This function is called for all elements that had their once removed. +}); + +<a name="findOnce"></a> +#findOnce(id) +Filters elements that have already been processed once. + +**Params** + +- id `string` - A required string representing the name of the data id which should be used + when filtering the elements. This only filters elements that have already + been processed by the once function. The id should be the same id that + was originally passed to the once() function. + +**Returns**: - jQuery element collection of elements that have been run once. +**Example** +// Find all elements that have the changecolor'ed once. +$('p').findOnce('changecolor').each(function() { + // This function is called for all elements that has already once'd. +}); + @@ -1,5 +1,9 @@ # History +## v2.0.x +- Added [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown) to + automatically generate API documentation + ## v2.0.0-beta.2 December 31, 2014 - Update documentation - Switched to [Mocha](http://mochajs.org) for automated testing @@ -58,81 +58,7 @@ be used to ensure that a function is only applied once to an element. ## Usage -### `.once(id)` - -Filter elements by whether they have not yet been processed. - -#### Parameters - -* `id` *string* (optional) The data id used to determine whether the given elements have -already been processed or not. Default: `once` - -#### Returns - -jQuery element collection of elements that have now run once by the given id. - -#### Example - -``` javascript -$('div.calendar').once('calendar').click(function() { - // .once('calendar') filters out all elements which already have been - // filtered with once('calendar'), and the elements that haven't been filtered - // yet remain. The previous set of elements can be restored with - // .end(). -}); -$('div.calendar').once().each(function() { - // This function is only executed once for each div, even if this - // code segment is executed repeatedly. Keyed by "once". -}); -``` - - -### `.findOnce(id)` - -After `.once()` is used and you need to retrieve all elements that have already -been executed with `.once()`, you can use the `.findOnce() function: - -#### Parameters - -* `id` *string* The data id used to determine whether the given elements have -already been processed or not. - -#### Returns - -jQuery element collection of elements that have been run once. - -#### Example - -``` javascript -$('div.calendar').findOnce('calendar').each(function() { - // This function is called for each element that was already called "once" - // with the "calendar" ID. -}); -``` - -### `.removeOnce(id)` - -A required string representing the name of the data id which should be used when -filtering the elements. This only filters elements that have already been processed by -the once function. The id should be the same id that was originally passed to the -`once()` function. - -#### Parameters - -* `id` *string* The data id used to determine whether the given elements have -already been processed or not. - -#### Returns - -jQuery element collection of elements that now have their once data removed. - -#### Example - -``` javascript -$('div.calendar').removeOnce('calendar').each(function() { - // This function is called for each element whose once() data is removed. -}); -``` +See the [API documentation](API.md) for details on how to use jQuery Once. ## Development @@ -146,13 +72,15 @@ Use [Mocha](http://mochajs.org) to test with [ESLint](http://eslint.org) and npm test -Update project documentation with [Projectz](https://github.com/bevry/projectz): +Update project documentation with [Projectz](https://github.com/bevry/projectz) +and [jsdoc-to-markdown](https://github.com/75lb/jsdoc-to-markdown): - npm run-script projectz + npm run projectz + npm run docs Build the project with: - npm run-script release + npm run release Tag and publish the new versions to [npm](http://npmjs.com): diff --git a/package.json b/package.json index 442f139..123eda1 100644 --- a/package.json +++ b/package.json @@ -51,6 +51,7 @@ }, "devDependencies": { "eslint": "~0.11.0-alpha.0", + "jsdoc-to-markdown": "^0.5.9", "jsdom": "^2.0.0", "mocha": "*", "mocha-jsdom": "^0.2.0", @@ -61,6 +62,7 @@ "pretest": "./node_modules/.bin/eslint jquery.once.js test/test.js", "test": "./node_modules/.bin/mocha", "projectz": "./node_modules/.bin/projectz compile", + "docs": "./node_modules/.bin/jsdoc2md jquery.once.js > API.md", "release": "./node_modules/.bin/uglifyjs jquery.once.js -o jquery.once.min.js --comments --source-map jquery.once.min.js.map --mangle" } -}
\ No newline at end of file +} |