Add docstring for tsdoc.

core/src/native.ts

@@ -20,9 +20,9 @@ import {
  * which supports only the ciphersuites that can be implemented on the native
  * {@link https://www.w3.org/TR/WebCryptoAPI/ | Web Cryptography API}.
  * Therefore, the following cryptographic algorithms are not supported for now:
- *   - DHKEM(X25519, HKDF-SHA256)
- *   - DHKEM(X448, HKDF-SHA512)
- *   - ChaCha20Poly1305
+ * - `DHKEM(X25519, HKDF-SHA256)`
+ * - `DHKEM(X448, HKDF-SHA512)`
+ * - `ChaCha20Poly1305`
  *
  * In addtion, the HKDF functions contained in this `CipherSuiteNative`
  * class can only derive keys of the same length as the `hashSize`.
@@ -34,11 +34,11 @@ import {
  * This class provides following functions:
  *
  * - Creates encryption contexts both for senders and recipients.
- *   - {@link createSenderContext}
- *   - {@link createRecipientContext}
+ *     - {@link createSenderContext}
+ *     - {@link createRecipientContext}
  * - Provides single-shot encryption API.
- *   - {@link seal}
- *   - {@link open}
+ *     - {@link seal}
+ *     - {@link open}
  *
  * The calling of the constructor of this class is the starting
  * point for HPKE operations for both senders and recipients.
@@ -74,9 +74,167 @@ import {
  */
 export class CipherSuite extends CipherSuiteNative {}
 
+/**
+ * The DHKEM(P-256, HKDF-SHA256) for HPKE KEM implementing {@link KemInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KemId.DhkemP256HkdfSha256`
+ * as follows:
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes128Gcm,
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP256HkdfSha256(),
+ *   kdf: new HkdfSha256(),
+ *   aead: new Aes128Gcm(),
+ * });
+ * ```
+ */
 export class DhkemP256HkdfSha256 extends DhkemP256HkdfSha256Native {}
+
+/**
+ * The DHKEM(P-384, HKDF-SHA384) for HPKE KEM implementing {@link KemInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KemId.DhkemP384HkdfSha384`
+ * as follows:
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes128Gcm,
+ *   CipherSuite,
+ *   DhkemP384HkdfSha384,
+ *   HkdfSha384,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP384HkdfSha384(),
+ *   kdf: new HkdfSha384(),
+ *   aead: new Aes128Gcm(),
+ * });
+ * ```
+ */
 export class DhkemP384HkdfSha384 extends DhkemP384HkdfSha384Native {}
+
+/**
+ * The DHKEM(P-521, HKDF-SHA512) for HPKE KEM implementing {@link KemInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KemId.DhkemP521HkdfSha512`
+ * as follows:
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes256Gcm,
+ *   CipherSuite,
+ *   DhkemP521HkdfSha512,
+ *   HkdfSha512,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP521HkdfSha512(),
+ *   kdf: new HkdfSha512(),
+ *   aead: new Aes256Gcm(),
+ * });
+ * ```
+ */
 export class DhkemP521HkdfSha512 extends DhkemP521HkdfSha512Native {}
+
+/**
+ * The HKDF-SHA256 for HPKE KDF implementing {@link KdfInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KdfId.HkdfSha256`.
+ *
+ * The KDF class can only derive keys of the same length as the `hashSize`.
+ * If you want to derive keys longer than the `hashSize`,
+ * please use {@link https://deno.land/x/hpke/mod.ts?s=CipherSuite | hpke-js#CipherSuite}.
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes128Gcm,
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP256HkdfSha256(),
+ *   kdf: new HkdfSha256(),
+ *   aead: new Aes128Gcm(),
+ * });
+ * ```
+ */
 export class HkdfSha256 extends HkdfSha256Native {}
+
+/**
+ * The HKDF-SHA384 for HPKE KDF implementing {@link KdfInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KdfId.HkdfSha384`.
+ *
+ * The KDF class can only derive keys of the same length as the `hashSize`.
+ * If you want to derive keys longer than the `hashSize`,
+ * please use {@link https://deno.land/x/hpke/mod.ts?s=CipherSuite | hpke-js#CipherSuite}.
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes128Gcm,
+ *   CipherSuite,
+ *   DhkemP384HkdfSha384,
+ *   HkdfSha384,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP384HkdfSha384(),
+ *   kdf: new HkdfSha384(),
+ *   aead: new Aes128Gcm(),
+ * });
+ * ```
+ */
 export class HkdfSha384 extends HkdfSha384Native {}
+
+/**
+ * The HKDF-SHA512 for HPKE KDF implementing {@link KdfInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `kem` parameter of {@link CipherSuiteParams} instead of `KdfId.HkdfSha512`.
+ *
+ * The KDF class can only derive keys of the same length as the `hashSize`.
+ * If you want to derive keys longer than the `hashSize`,
+ * please use {@link https://deno.land/x/hpke/mod.ts?s=CipherSuite | hpke-js#CipherSuite}.
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes256Gcm,
+ *   CipherSuite,
+ *   DhkemP521HkdfSha512,
+ *   HkdfSha512,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP521HkdfSha512(),
+ *   kdf: new HkdfSha512(),
+ *   aead: new Aes256Gcm(),
+ * });
+ * ```
+ */
 export class HkdfSha512 extends HkdfSha512Native {}

src/aeads/aesGcm.ts

@@ -75,20 +75,75 @@ export class AesGcmContext extends NativeAlgorithm
   }
 }
 
+/**
+ * The AES-128-GCM for HPKE AEAD implementing {@link AeadInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `aead` parameter of {@link CipherSuiteParams} instead of `AeadId.Aes128Gcm`.
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes128Gcm,
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP256HkdfSha256(),
+ *   kdf: new HkdfSha256(),
+ *   aead: new Aes128Gcm(),
+ * });
+ * ```
+ */
 export class Aes128Gcm implements AeadInterface {
+  /** AeadId.Aes128Gcm (0x0001) */
   public readonly id: AeadId = AeadId.Aes128Gcm;
+  /** 16 */
   public readonly keySize: number = 16;
+  /** 12 */
   public readonly nonceSize: number = 12;
+  /** 16 */
   public readonly tagSize: number = 16;
 
   public createEncryptionContext(key: ArrayBuffer): AeadEncryptionContext {
     return new AesGcmContext(key);
   }
 }
 
+/**
+ * The AES-256-GCM for HPKE AEAD implementing {@link AeadInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `aead` parameter of {@link CipherSuiteParams} instead of `AeadId.Aes256Gcm`
+ * as follows:
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   Aes256Gcm,
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP256HkdfSha256(),
+ *   kdf: new HkdfSha256(),
+ *   aead: new Aes256Gcm(),
+ * });
+ * ```
+ */
 export class Aes256Gcm extends Aes128Gcm {
+  /** AeadId.Aes256Gcm (0x0002) */
   public readonly id: AeadId = AeadId.Aes256Gcm;
+  /** 32 */
   public readonly keySize: number = 32;
+  /** 12 */
   public readonly nonceSize: number = 12;
+  /** 16 */
   public readonly tagSize: number = 16;
 }

src/aeads/chacha20Poly1305.ts

@@ -61,30 +61,42 @@ export class Chacha20Poly1305Context implements AeadEncryptionContext {
 }
 
 /**
- * The ChaCha20Poly1305 AEAD.
+ * The ChaCha20Poly1305 for HPKE AEAD implementing {@link AeadInterface}.
  *
- * This class is implemented using
- * {@link https://github.com/paulmillr/noble-ciphers | @noble/ciphers}.
- *
- * The instance of this class can be specified to the
- * {@link https://deno.land/x/hpke/core/mod.ts?s=CipherSuiteParams | CipherSuiteParams} as follows:
+ * When using `@hpke/core`, the instance of this class can be specified
+ * to the `aead` parameter of {@link CipherSuiteParams} instead of `AeadId.Chacha20Poly1305`
+ * as follows:
  *
  * @example
  *
  * ```ts
- * import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from "http://deno.land/x/hpke/core/mod.ts";
- * import { Chacha20Poly1305 } from "https://deno.land/x/hpke/x/chach20poly1305/mod.ts";
+ * import {
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ * import {
+ *   Chacha20Poly1305,
+ * } from "https://deno.land/x/hpke/x/chach20poly1305/mod.ts";
+ *
  * const suite = new CipherSuite({
  *   kem: new DhkemP256HkdfSha256(),
  *   kdf: new HkdfSha256(),
  *   aead: new Chacha20Poly1305(),
  * });
  * ```
+ *
+ * This class is implemented using
+ * {@link https://github.com/paulmillr/noble-ciphers | @noble/ciphers}.
  */
 export class Chacha20Poly1305 implements AeadInterface {
+  /** AeadId.Chacha20Poly1305 (0x0003) */
   public readonly id: AeadId = AeadId.Chacha20Poly1305;
+  /** 32 */
   public readonly keySize: number = 32;
+  /** 12 */
   public readonly nonceSize: number = 12;
+  /** 16 */
   public readonly tagSize: number = 16;
 
   public createEncryptionContext(key: ArrayBuffer): AeadEncryptionContext {

src/aeads/exportOnly.ts

@@ -5,6 +5,30 @@ import { AeadId } from "../identifiers.ts";
 
 import { NotSupportedError } from "../errors.ts";
 
+/**
+ * The ExportOnly mode for HPKE AEAD implementing {@link AeadInterface}.
+ *
+ * When using `@hpke/core`, the instance of this class must be specified
+ * to the `aead` parameter of {@link CipherSuiteParams} instead of `AeadId.ExportOnly`
+ * as follows:
+ *
+ * @example
+ *
+ * ```ts
+ * import {
+ *   CipherSuite,
+ *   DhkemP256HkdfSha256,
+ *   ExportOnly,
+ *   HkdfSha256,
+ * } from "http://deno.land/x/hpke/core/mod.ts";
+ *
+ * const suite = new CipherSuite({
+ *   kem: new DhkemP256HkdfSha256(),
+ *   kdf: new HkdfSha256(),
+ *   aead: new ExportOnly(),
+ * });
+ * ```
+ */
 export class ExportOnly implements AeadInterface {
   public readonly id: AeadId = AeadId.ExportOnly;
   public readonly keySize: number = 0;

src/cipherSuite.ts

@@ -22,7 +22,6 @@ import { CipherSuiteNative } from "./cipherSuiteNative.ts";
  * {@link https://datatracker.ietf.org/doc/html/rfc9180 | RFC9180}.
  *
  * The class consists of the {@link https://deno.land/x/hpke/core/mod.ts | @hpke/core},
- * {@link https://deno.land/x/hpke/core/mod.ts | @hpke/core},
  * {@link https://deno.land/x/hpke/x/chacha20Poly1305/mod.ts | @hpke/chcha20poly1305},
  * {@link https://deno.land/x/hpke/x/dhkem-x25519/mod.ts | @hpke/dhkem-x25519} and
  * {@link https://deno.land/x/hpke/x/dhkem-x448/mod.ts | @hpke/dhkem-x448} internally.
@@ -33,11 +32,11 @@ import { CipherSuiteNative } from "./cipherSuiteNative.ts";
  * - [DEPRECATED] Derives a key pair for the cipher suite.
  * - [DEPRECATED] Imports and converts a key to a CryptoKey.
  * - Creates encryption contexts both for senders and recipients.
- *   - {@link createSenderContext}
- *   - {@link createRecipientContext}
+ *     - {@link createSenderContext}
+ *     - {@link createRecipientContext}
  * - Provides single-shot encryption API.
- *   - {@link seal}
- *   - {@link open}
+ *     - {@link seal}
+ *     - {@link open}
  *
  * The calling of the constructor of this class is the starting
  * point for HPKE operations for both senders and recipients.