more detailed doc

README.md

@@ -1,12 +1,37 @@
 # Qyu ![](https://travis-ci.org/adrienjoly/algolia-qyu.svg?branch=master)
 
-## An in-memory queue in JavaScript
+## An in-memory job queue in JavaScript
 
-This queue can run asynchronous jobs sequentially (with `rateLimit = null`) or concurrently (with maximum number of jobs that can be run per second, in `rateLimit`).
+Qyu runs asynchronous jobs sequentially (with `rateLimit = null`) or concurrently (with maximum number of jobs that can be run per second, in `rateLimit`).
 
-Documentation: [qyu API docs](https://adrienjoly.com/algolia-qyu/) (Generated by JSDoc)
+This codebase was proposed as a solution of [Algolia's Qyu challenge](challenge.md), for evaluation purposes.
 
-⚠️ This implementation is **not intended for production use**, and the underlying data structure is **not safe to use in a multi-threaded environment**.
+⚠️ **Important**: It's **not intended for production use**, and the underlying data structure is **not safe to use in a multi-threaded environment**.
+
+## Design / how it works
+
+The library exports a function that instantiates the Qyu class.
+
+The Qyu class provides the following methods:
+
+- `push()`: add a job (asynchronous function) to the queue, with optional priority
+- `start()`: start processing jobs from the queue
+- `pause()`: pause processing of jobs, until `start()` is called again
+
+Each instance of Qyu also emits the following events:
+
+- `done`: when a job is done without error
+- `error`: when a job ends with an error
+- `stats`: regularly provides the number of jobs that are processed by second
+- `drain`: when the queue is empty (no more jobs to process)
+
+Qyu relies on the `RateLimiter` class to throttle the processing of jobs (i.e. maximum number of jobs processed by second, as specified by the `rateLimit` parameter), and to emit `stats` events (as specified by the `statsInterval` parameter).
+
+Here is a sequence diagram to illustrate the collaboration between Qyu and its RateLimiter:
+
+![sequence diagram](docs/seq-diagram.svg)
+
+For more information, please refer to our reference documentation: [Qyu API docs](https://adrienjoly.com/algolia-qyu/) (Generated by JSDoc)
 
 ## Prerequisites
 
@@ -21,10 +46,6 @@ $ npm install
 $ npm test
 ```
 
-## Design
-
-![sequence diagram](docs/seq-diagram.svg)
-
 ## Example of use
 
 Here's a minimal example of use:

qyu.js

@@ -1,9 +1,3 @@
-// proposed implementation for the "qyu" queue
-
-// useful to get stack traces from UnhandledPromiseRejectionWarning errors:
-//process.on('unhandledRejection', r => console.error(r));
-// see https://github.com/nodejs/node/issues/9523#issuecomment-259303079
-
 const EventEmitter = require('events');
 const RateLimiter = require('./RateLimiter');
 
@@ -22,7 +16,7 @@ const DEFAULT_JOB_OPTIONS = {
 var nextJobId = 0; // global job counter, used to generate unique ids
 
 /**
- * Holds, controls and reports on execution of a queue of jobs.
+ * Holds, controls and reports on execution of a queue of asynchronous jobs.
  * @fires Qyu#done
  * @fires Qyu#error
  * @fires Qyu#drain
@@ -232,3 +226,7 @@ function qyu(opts) {
 }
 
 module.exports = qyu;
+
+// useful to get stack traces from UnhandledPromiseRejectionWarning errors:
+//process.on('unhandledRejection', r => console.error(r));
+// see https://github.com/nodejs/node/issues/9523#issuecomment-259303079