Redacted: add JSDocs (#2944)

packages/effect/src/Redacted.ts

@@ -1,4 +1,9 @@
 /**
+ * The Redacted module provides functionality for handling sensitive information
+ * securely within your application. By using the `Redacted` data type, you can
+ * ensure that sensitive values are not accidentally exposed in logs or error
+ * messages.
+ *
  * @since 3.3.0
  */
 import type * as Equal from "./Equal.js"
@@ -54,24 +59,73 @@ export declare namespace Redacted {
 export const isRedacted: (u: unknown) => u is Redacted<unknown> = redacted_.isRedacted
 
 /**
+ * This function creates a `Redacted<A>` instance from a given value `A`,
+ * securely hiding its content.
+ *
+ * @example
+ * import { Redacted } from "effect"
+ *
+ * const API_KEY = Redacted.make("1234567890")
+ *
  * @since 3.3.0
  * @category constructors
  */
 export const make: <A>(value: A) => Redacted<A> = redacted_.make
 
 /**
+ * Retrieves the original value from a `Redacted` instance. Use this function
+ * with caution, as it exposes the sensitive data.
+ *
+ * @example
+ * import { Redacted } from "effect"
+ *
+ * const API_KEY = Redacted.make("1234567890")
+ *
+ * assert.equal(Redacted.value(API_KEY), "1234567890")
+ *
  * @since 3.3.0
  * @category getters
  */
 export const value: <A>(self: Redacted<A>) => A = redacted_.value
 
 /**
+ * Erases the underlying value of a `Redacted` instance, rendering it unusable.
+ * This function is intended to ensure that sensitive data does not remain in
+ * memory longer than necessary.
+ *
+ * @example
+ * import { Redacted } from "effect"
+ *
+ * const API_KEY = Redacted.make("1234567890")
+ *
+ * assert.equal(Redacted.value(API_KEY), "1234567890")
+ *
+ * Redacted.unsafeWipe(API_KEY)
+ *
+ * assert.throws(() => Redacted.value(API_KEY), new Error("Unable to get redacted value"))
+ *
  * @since 3.3.0
  * @category unsafe
  */
 export const unsafeWipe: <A>(self: Redacted<A>) => boolean = redacted_.unsafeWipe
 
 /**
+ * Generates an equivalence relation for `Redacted<A>` values based on an
+ * equivalence relation for the underlying values `A`. This function is useful
+ * for comparing `Redacted` instances without exposing their contents.
+ *
+ * @example
+ * import { Redacted, Equivalence } from "effect"
+ *
+ * const API_KEY1 = Redacted.make("1234567890")
+ * const API_KEY2 = Redacted.make("1-34567890")
+ * const API_KEY3 = Redacted.make("1234567890")
+ *
+ * const equivalence = Redacted.getEquivalence(Equivalence.string)
+ *
+ * assert.equal(equivalence(API_KEY1, API_KEY2), false)
+ * assert.equal(equivalence(API_KEY1, API_KEY3), true)
+ *
  * @category equivalence
  * @since 3.3.0
  */

packages/effect/src/index.ts

@@ -615,6 +615,11 @@ export * as Record from "./Record.js"
 export * as RedBlackTree from "./RedBlackTree.js"
 
 /**
+ * The Redacted module provides functionality for handling sensitive information
+ * securely within your application. By using the `Redacted` data type, you can
+ * ensure that sensitive values are not accidentally exposed in logs or error
+ * messages.
+ *
  * @since 3.3.0
  */
 export * as Redacted from "./Redacted.js"