priority-queue: set-up auto-generated API docs (#14262)

WordPress · Mar 20, 2019 · 6dfdbbb · 6dfdbbb
1 parent 9b9df1b
commit 6dfdbbb
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 4 deletions.
diff --git a/bin/update-readmes.js b/bin/update-readmes.js
@@ -26,7 +26,7 @@ const packages = [
 	'i18n',
 	'keycodes',
 	//'plugins',
-	//'priority-queue',
+	'priority-queue',
 	//'redux-routine',
 	'rich-text',
 	//'shortcode',

diff --git a/packages/priority-queue/README.md b/packages/priority-queue/README.md
@@ -10,9 +10,20 @@ Install the module
 npm install @wordpress/priority-queue --save
 ```
 
-_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats).
+_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
 
-## Usage
+## API
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+### createQueue
+
+[src/index.js#L25-L72](src/index.js#L25-L72)
+
+Creates a context-aware queue that only executes
+the last task of a given context.
+
+**Usage**
 
 ```js
 import { createQueue } from '@wordpress/priority-queue';
@@ -21,12 +32,19 @@ const queue = createQueue();
 
 // Context objects.
 const ctx1 = {};
-const ctx2 = {}; 
+const ctx2 = {};
 
 // For a given context in the queue, only the last callback is executed.
 queue.add( ctx1, () => console.log( 'This will be printed first' ) );
 queue.add( ctx2, () => console.log( 'This won\'t be printed' ) );
 queue.add( ctx2, () => console.log( 'This will be printed second' ) );
 ```
 
+**Returns**
+
+`Object`: Queue object with `add` and `flush` methods.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/priority-queue/src/index.js b/packages/priority-queue/src/index.js
@@ -1,5 +1,27 @@
 const requestIdleCallback = window.requestIdleCallback ? window.requestIdleCallback : window.requestAnimationFrame;
 
+/**
+ * Creates a context-aware queue that only executes
+ * the last task of a given context.
+ *
+ * @example
+ *```js
+ * import { createQueue } from '@wordpress/priority-queue';
+ *
+ * const queue = createQueue();
+ *
+ * // Context objects.
+ * const ctx1 = {};
+ * const ctx2 = {};
+ *
+ * // For a given context in the queue, only the last callback is executed.
+ * queue.add( ctx1, () => console.log( 'This will be printed first' ) );
+ * queue.add( ctx2, () => console.log( 'This won\'t be printed' ) );
+ * queue.add( ctx2, () => console.log( 'This will be printed second' ) );
+ *```
+ *
+ * @return {Object} Queue object with `add` and `flush` methods.
+ */
 export const createQueue = () => {
 	const waitingList = [];
 	const elementsMap = new WeakMap();