From c9d09abebc7cf0aa92c74fbc1d6e13ba25df0093 Mon Sep 17 00:00:00 2001
From: Ruben Verborgh <ruben@verborgh.org>
Date: Thu, 9 Sep 2021 08:11:47 +0100
Subject: [PATCH] docs: Update AsyncHandler documentation.

---
 src/util/handlers/AsyncHandler.ts | 22 ++++++++++------------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/src/util/handlers/AsyncHandler.ts b/src/util/handlers/AsyncHandler.ts
index 1deb8408c..52e42a572 100644
--- a/src/util/handlers/AsyncHandler.ts
+++ b/src/util/handlers/AsyncHandler.ts
@@ -3,9 +3,9 @@
  */
 export abstract class AsyncHandler<TIn = void, TOut = void> {
   /**
-   * Checks if the input data can be handled by this class.
-   * Throws an error if it can't handle the data.
-   * @param input - Input data that could potentially be handled.
+   * Checks if the input can be handled by this class.
+   * If it cannot handle the input, rejects with an error explaining why.
+   * @param input - Input that could potentially be handled.
    *
    * @returns A promise resolving if the input can be handled, rejecting with an Error if not.
    */
@@ -15,26 +15,24 @@ export abstract class AsyncHandler<TIn = void, TOut = void> {
   }
 
   /**
-   * Handles the given input. This should only be done if the {@link canHandle} function returned `true`.
-   * Therefore, consider using the {@link handleSafe} function instead.
-   * @param input - Input data that needs to be handled.
+   * Handles the given input. This may only be called if {@link canHandle} did not reject.
+   * When unconditionally calling both in sequence, consider {@link handleSafe} instead.
+   * @param input - Input that needs to be handled.
    *
-   * @returns A promise resolving when the handling is finished. Return value depends on the given type.
+   * @returns A promise resolving when handling is finished.
    */
   public abstract handle(input: TIn): Promise<TOut>;
 
   /**
-   * Helper function that first runs the canHandle function followed by the handle function.
-   * Throws the error of the {@link canHandle} function if the data can't be handled,
-   * or returns the result of the {@link handle} function otherwise.
+   * Helper function that first runs {@link canHandle} followed by {@link handle}.
+   * Throws the error of {@link canHandle} if the data cannot be handled,
+   * or returns the result of {@link handle} otherwise.
    * @param input - Input data that will be handled if it can be handled.
    *
    * @returns A promise resolving if the input can be handled, rejecting with an Error if not.
-   * Return value depends on the given type.
    */
   public async handleSafe(input: TIn): Promise<TOut> {
     await this.canHandle(input);
-
     return this.handle(input);
   }
 }