docs: fix outdated circuitbreaker doc, unnecessary param dashes

Fixes #23
Fixes #24
Fixes #22

changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## TBA
+
+- **docs:** fix outdated docs on `Policy.circuitBreaker` and unnecessary dashes in jsdoc comments (see [#22](https://github.com/connor4312/cockatiel/issues/22), [#23](https://github.com/connor4312/cockatiel/issues/23), [#24](https://github.com/connor4312/cockatiel/issues/24))
+
 ## 1.0.1 - 2020-06-22
 
 - **fix:** cockatiel not working in certain browser builds

src/BulkheadPolicy.ts

@@ -55,7 +55,7 @@ export class BulkheadPolicy implements IPolicy<void> {
 
   /**
    * Executes the given function.
-   * @param fn -- Function to execute
+   * @param fn Function to execute
    * @throws a {@link BulkheadRejectedException} if the bulkhead limits are exceeeded
    */
   public async execute<T>(fn: (context: void) => PromiseLike<T> | T): Promise<T> {

src/CircuitBreakerPolicy.ts

@@ -136,7 +136,7 @@ export class CircuitBreakerPolicy implements IPolicy<void> {
 
   /**
    * Executes the given function.
-   * @param fn -- Function to run
+   * @param fn Function to run
    * @throws a {@link BrokenCircuitError} if the circuit is open
    * @throws a {@link IsolatedCircuitError} if the circuit is held
    * open via {@link CircuitBreakerPolicy.isolate}

src/FallbackPolicy.ts

@@ -18,7 +18,7 @@ export class FallbackPolicy<AltReturn> implements IPolicy<void, AltReturn> {
 
   /**
    * Executes the given function.
-   * @param fn -- Function to execute.
+   * @param fn Function to execute.
    * @returns The function result or fallback value.
    */
   public async execute<T>(fn: (context: void) => PromiseLike<T> | T): Promise<T | AltReturn> {

src/Policy.ts

@@ -287,8 +287,8 @@ export class Policy {
   /**
    * Allows the policy to additionally handles errors of the given type.
    *
-   * @param cls -- Class constructor to check that the error is an instance of.
-   * @param predicate -- If provided, a function to be called with the error
+   * @param cls Class constructor to check that the error is an instance of.
+   * @param predicate If provided, a function to be called with the error
    * which should return "true" if we want to handle this error.
    * @example
    * ```js
@@ -313,7 +313,7 @@ export class Policy {
    * Allows the policy to additionally handles errors that pass the given
    * predicate function.
    *
-   * @param predicate -- Takes any thrown error, and returns true if it should
+   * @param predicate Takes any thrown error, and returns true if it should
    * be retried by this policy.
    * @example
    * ```js
@@ -336,7 +336,7 @@ export class Policy {
    * Adds handling for return values. The predicate will be called with
    * the return value of the executed function,
    *
-   * @param predicate -- Takes the returned value, and returns true if it
+   * @param predicate Takes the returned value, and returns true if it
    * should be retried by this policy.
    * @example
    * ```js
@@ -359,7 +359,7 @@ export class Policy {
    * Adds handling for return values. The predicate will be called with
    * the return value of the executed function,
    *
-   * @param predicate -- Takes the returned value, and returns true if it
+   * @param predicate Takes the returned value, and returns true if it
    * should be retried by this policy.
    * @example
    * ```js
@@ -400,17 +400,17 @@ export class Policy {
    * // Break if more than 20% of requests fail in a 30 second time window:
    * const breaker = Policy
    *  .handleAll()
-   *  .circuitBreaker(new SamplingBreaker(0.2, 30 * 1000));
+   *  .circuitBreaker(10_000, new SamplingBreaker(0.2, 30 * 1000));
    *
    * export function handleRequest() {
    *   return breaker.execute(() => getInfoFromDatabase());
    * }
    * ```
    *
-   * @param breaker -- The circuit breaker to use. This package exports
-   * ConsecutiveBreaker and SamplingBreakers for you to use.
-   * @param halfOpenAfter -- Time after failures to try to open the circuit
+   * @param halfOpenAfter Time after failures to try to open the circuit
    * breaker again. Defaults to 10 seconds.
+   * @param breaker The circuit breaker to use. This package exports
+   * ConsecutiveBreaker and SamplingBreakers for you to use.
    */
   public circuitBreaker(halfOpenAfter: number, breaker: IBreaker) {
     return new CircuitBreakerPolicy(
@@ -437,7 +437,7 @@ export class Policy {
    * }
    * ```
    *
-   * @param toValue -- Value to fall back to, or a function that creates the
+   * @param toValue Value to fall back to, or a function that creates the
    * value to return (any may return a promise)
    */
   public fallback<R>(valueOrFactory: (() => Promise<R> | R) | R) {

src/RetryPolicy.ts

@@ -82,7 +82,7 @@ export class RetryPolicy implements IPolicy<IRetryContext> {
 
   /**
    * Sets the number of retry attempts for the function.
-   * @param count -- Retry attempts to make
+   * @param count Retry attempts to make
    */
   public attempts(count: number) {
     return this.composeBackoff('a', new ConstantBackoff(1, count));
@@ -132,7 +132,7 @@ export class RetryPolicy implements IPolicy<IRetryContext> {
 
   /**
    * Executes the given function with retries.
-   * @param fn -- Function to run
+   * @param fn Function to run
    * @returns a Promise that resolves or rejects with the function results.
    */
   public async execute<T>(fn: (context: IRetryContext) => PromiseLike<T> | T): Promise<T> {

src/TimeoutPolicy.ts

@@ -63,7 +63,7 @@ export class TimeoutPolicy implements IPolicy<ICancellationContext> {
 
   /**
    * Executes the given function.
-   * @param fn -- Function to execute. Takes in a nested cancellation token.
+   * @param fn Function to execute. Takes in a nested cancellation token.
    * @throws a {@link TaskCancelledError} if a timeout occurs
    */
   public async execute<T>(fn: (context: ICancellationContext) => PromiseLike<T> | T): Promise<T> {