docs: Add caution about suppressing errors (#174)

The TSDoc comment for `createDeferredPromise` has been updated to
include a caution about using the `suppressUnhandledRejection` option.
The comment now explains in more detail why this option is useful, and
why it can be dangerous and should be treated with caution.

src/promise.ts

@@ -23,6 +23,16 @@ export type DeferredPromise<Result = void> = {
 /**
  * Create a defered Promise.
  *
+ * If the Promise is rejected prior to a handler being added, this can result in an
+ * `UnhandledPromiseRejection` error. Optionally this can be suppressed with the
+ * `suppressUnhandledRejection` flag, as it's common to belatedly handle deferred Promises, or to
+ * ignore them if they're no longer relevant (e.g. related to a cancelled request).
+ *
+ * However, be very careful that you have handled the Promise if you do this. Suppressing these
+ * errors is dangerous, they exist for good reason. An unhandled rejection can hide errors, making
+ * debugging extremely difficult. They should only be suppressed if you're confident that the
+ * Promise is always handled correctly, in both the success and failure cases.
+ *
  * @param args - The arguments.
  * @param args.suppressUnhandledRejection - This option adds an empty error handler
  * to the Promise to suppress the UnhandledPromiseRejection error. This can be