fix: JSDoc now available for semaphore-locked event

lib/circuit.js

@@ -22,31 +22,31 @@ const CACHE = new WeakMap();
  *
  * @class CircuitBreaker
  * @extends EventEmitter
- * @param action {function} The action to fire for this {@link CircuitBreaker} instance
+ * @param action {Function} The action to fire for this {@link CircuitBreaker} instance
  * @param options {Object} Options for the {@link CircuitBreaker}.
  * There are **no default options** when you use the contructor directly. You
  * must supply values for each of these.
- * @param options.timeout {number} The time in milliseconds that action should
+ * @param options.timeout {Number} The time in milliseconds that action should
  * be allowed to execute before timing out.
- * @param options.maxFailures The number of times the circuit can fail before
- * opening. (deprecated - see options.errorThresholdPercentage)
- * @param options.resetTimeout The time in milliseconds to wait before setting
+ * @param options.maxFailures {Number} The number of times the circuit can fail before
+ * opening. (deprecated - see {CircuitBreaker#options.errorThresholdPercentage})
+ * @param options.resetTimeout {Number} The time in milliseconds to wait before setting
  * the breaker to `halfOpen` state, and trying the action again.
- * @param options.rollingCountTimeout Sets the duration of the statistical
+ * @param options.rollingCountTimeout {Number} Sets the duration of the statistical
  *  rolling window, in milliseconds. This is how long Opossum keeps metrics for
  *  the circuit breaker to use and for publishing. Default: 10000
- * @param options.rollingCountBuckets sets the number of buckets the rolling
+ * @param options.rollingCountBuckets {Number} sets the number of buckets the rolling
  *  statistical window is divided into. So, if options.rollingCountTimeout is
  *  10000, and options.rollingCountBuckets is 10, then the statistical window
  *  will be 1000 1 second snapshots in the statistical window. Default: 10
- * @param options.name the name to use for this circuit when reporting stats
- * @param options.rollingPercentilesEnabled {boolean} This property indicates whether execution latencies
+ * @param options.name {String} the name to use for this circuit when reporting stats
+ * @param options.rollingPercentilesEnabled {Boolean} This property indicates whether execution latencies
  *  should be tracked and calculated as percentiles.
  *  If they are disabled, all summary statistics (mean, percentiles) are returned as -1.
- * @param options.capacity the number of concurrent requests allowed. If the number of
+ * @param options.capacity {Number} the number of concurrent requests allowed. If the number of
  * currently executing function calls is equal to options.capacity, further calls to `fire()`
  * are rejected until at least one of the current requests completes.
- * @param options.errorThresholdPercentage the error percentage at which to open
+ * @param options.errorThresholdPercentage {Number} the error percentage at which to open
  * the circuit and start short-circuiting requests to fallback logic.
  */
 class CircuitBreaker extends EventEmitter {
@@ -233,7 +233,7 @@ class CircuitBreaker extends EventEmitter {
    * resolve with the resolved value from action. If a fallback function has been
    * provided, it will be invoked in the event of any failure or timeout.
    *
-   * @return {@link Promise} a Promise that resolves on success and is rejected
+   * @return a Promise which resolves on success and is rejected
    * on failure of the action.
    *
    * @fires CircuitBreaker#failure
@@ -242,6 +242,7 @@ class CircuitBreaker extends EventEmitter {
    * @fires CircuitBreaker#reject
    * @fires CircuitBreaker#success
    * @fires CircuitBreaker#timeout
+   * @fires CircuitBreaker#semaphore-locked
    */
   fire () {
     const args = Array.prototype.slice.call(arguments);
@@ -336,6 +337,11 @@ class CircuitBreaker extends EventEmitter {
         const latency = Date.now() - latencyStartTime;
         const err = new Error('Semaphore locked');
         err.code = 'ESEMLOCKED';
+        /**
+         * Emitted when the rate limit has been reached and there
+         * are no more locks to be obtained.
+         * @event CircuitBreaker#semaphore-locked
+         */
         this.emit('semaphore-locked', err, latency);
         handleError(err, this, timeout, args, latency, resolve, reject);
       }