Document @solana/assertions with TypeDoc (#64)

anza-xyz · Jan 20, 2025 · cd07559 · cd07559
1 parent fabec8f
commit cd07559
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 4 deletions.
diff --git 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
@@ -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
@@ -36,13 +36,21 @@ 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') {
         throw new SolanaError(SOLANA_ERROR__SUBTLE_CRYPTO__DIGEST_UNIMPLEMENTED);
     }
 }
 
+/**
+ * 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,20 +61,31 @@ 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') {
         throw new SolanaError(SOLANA_ERROR__SUBTLE_CRYPTO__EXPORT_FUNCTION_UNIMPLEMENTED);
     }
 }
 
+/**
+ * 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
@@ -1,5 +1,6 @@
 {
     "$schema": "https://typedoc.org/schema.json",
     "extends": ["../typedoc.base.json"],
-    "entryPoints": ["src/index.ts"]
+    "entryPoints": ["src/index.ts"],
+    "readme": "none"
 }