From cd0755909f803b6117d115e50a86c7a7103d8aac Mon Sep 17 00:00:00 2001
From: Steven Luscher <steveluscher@users.noreply.github.com>
Date: Mon, 20 Jan 2025 01:29:44 -0800
Subject: [PATCH] Document `@solana/assertions` with TypeDoc (#64)

---
 packages/assertions/src/crypto.ts        |  4 ++++
 packages/assertions/src/index.ts         |  9 +++++++--
 packages/assertions/src/subtle-crypto.ts | 21 ++++++++++++++++++++-
 packages/assertions/typedoc.json         |  3 ++-
 4 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/packages/assertions/src/crypto.ts b/packages/assertions/src/crypto.ts
index 8752465e8..9a6ee26f6 100644
--- a/packages/assertions/src/crypto.ts
+++ b/packages/assertions/src/crypto.ts
@@ -1,5 +1,9 @@
 import { SOLANA_ERROR__CRYPTO__RANDOM_VALUES_FUNCTION_UNIMPLEMENTED, SolanaError } from '@solana/errors';
 
+/**
+ * Throws an exception unless {@link Crypto#getRandomValues | `crypto.getRandomValues()`} is
+ * available in the current JavaScript environment.
+ */
 export function assertPRNGIsAvailable() {
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.getRandomValues !== 'function') {
         throw new SolanaError(SOLANA_ERROR__CRYPTO__RANDOM_VALUES_FUNCTION_UNIMPLEMENTED);
diff --git a/packages/assertions/src/index.ts b/packages/assertions/src/index.ts
index 98dfc6ace..76ab52968 100644
--- a/packages/assertions/src/index.ts
+++ b/packages/assertions/src/index.ts
@@ -1,3 +1,8 @@
-export * from './subtle-crypto';
-
+/**
+ * This package contains utilities for asserting that a JavaScript environment supports certain
+ * features necessary for the operation of the Solana JavaScript SDK.
+ *
+ * @packageDocumentation
+ */
 export * from './crypto';
+export * from './subtle-crypto';
diff --git a/packages/assertions/src/subtle-crypto.ts b/packages/assertions/src/subtle-crypto.ts
index 4ca6d6686..08d124537 100644
--- a/packages/assertions/src/subtle-crypto.ts
+++ b/packages/assertions/src/subtle-crypto.ts
@@ -36,6 +36,10 @@ async function isEd25519CurveSupported(subtle: SubtleCrypto): Promise<boolean> {
     }
 }
 
+/**
+ * Throws an exception unless {@link SubtleCrypto#digest | `crypto.subtle.digest()`} is available in
+ * the current JavaScript environment.
+ */
 export function assertDigestCapabilityIsAvailable() {
     assertIsSecureContext();
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.subtle?.digest !== 'function') {
@@ -43,6 +47,10 @@ export function assertDigestCapabilityIsAvailable() {
     }
 }
 
+/**
+ * Throws an exception unless {@link SubtleCrypto#generateKey | `crypto.subtle.generateKey()`} is
+ * available in the current JavaScript environment and has support for the Ed25519 curve.
+ */
 export async function assertKeyGenerationIsAvailable() {
     assertIsSecureContext();
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.subtle?.generateKey !== 'function') {
@@ -53,6 +61,10 @@ export async function assertKeyGenerationIsAvailable() {
     }
 }
 
+/**
+ * Throws an exception unless {@link SubtleCrypto#exportKey | `crypto.subtle.exportKey()`} is
+ * available in the current JavaScript environment.
+ */
 export function assertKeyExporterIsAvailable() {
     assertIsSecureContext();
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.subtle?.exportKey !== 'function') {
@@ -60,13 +72,20 @@ export function assertKeyExporterIsAvailable() {
     }
 }
 
+/**
+ * Throws an exception unless {@link SubtleCrypto#sign | `crypto.subtle.sign()`} is available in the
+ * current JavaScript environment.
+ */
 export function assertSigningCapabilityIsAvailable() {
     assertIsSecureContext();
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.subtle?.sign !== 'function') {
         throw new SolanaError(SOLANA_ERROR__SUBTLE_CRYPTO__SIGN_FUNCTION_UNIMPLEMENTED);
     }
 }
-
+/**
+ * Throws an exception unless {@link SubtleCrypto#verify | `crypto.subtle.verify()`} is available in
+ * the current JavaScript environment.
+ */
 export function assertVerificationCapabilityIsAvailable() {
     assertIsSecureContext();
     if (typeof globalThis.crypto === 'undefined' || typeof globalThis.crypto.subtle?.verify !== 'function') {
diff --git a/packages/assertions/typedoc.json b/packages/assertions/typedoc.json
index d99f37ef3..3a90a65cc 100644
--- a/packages/assertions/typedoc.json
+++ b/packages/assertions/typedoc.json
@@ -1,5 +1,6 @@
 {
     "$schema": "https://typedoc.org/schema.json",
     "extends": ["../typedoc.base.json"],
-    "entryPoints": ["src/index.ts"]
+    "entryPoints": ["src/index.ts"],
+    "readme": "none"
 }