Clean-up comments

src/_crystals.ts

@@ -1,5 +1,5 @@
 /**
- * Methods for lattices on ML-KEM and ML-DSA.
+ * Internal methods for lattice-based ML-KEM and ML-DSA.
  * @module
  */
 /*! noble-post-quantum - MIT License (c) 2024 Paul Miller (paulmillr.com) */

src/index.ts

@@ -1,8 +1,9 @@
 /**
  * Auditable & minimal JS implementation of post-quantum public-key cryptography.
  * Check out individual modules.
+ * @module
  * @example
-
+```js
 import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem';
 import { ml_dsa44, ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa';
 import {
@@ -13,7 +14,6 @@ import {
   slh_dsa_shake_192f, slh_dsa_shake_192s,
   slh_dsa_shake_256f, slh_dsa_shake_256s,
 } from '@noble/post-quantum/slh-dsa';
-
- * @module
+```
  */
 throw new Error('root module cannot be imported: import submodules instead. Check out README');

src/ml-dsa.ts

@@ -1,6 +1,6 @@
 /**
- * Module Lattice-based Digital Signature Algorithm (ML-DSA). A.k.a. CRYSTALS-Dilithium.
- * FIPS-204 is implemented.
+ * ML-DSA: Module Lattice-based Digital Signature Algorithm from
+ * [FIPS-204](https://csrc.nist.gov/pubs/fips/204/ipd). A.k.a. CRYSTALS-Dilithium.
  *
  * Has similar internals to ML-KEM, but their keys and params are different.
  * Check out [official site](https://www.pq-crystals.org/dilithium/index.shtml),
@@ -529,7 +529,7 @@ function getDilithium(opts: DilithiumOpts) {
 /** Signer API, containing internal methods */
 export type SignerWithInternal = Signer & { internal: Signer };
 
-/** ML-DSA-44 for 128-bit security level. As per ASD, not recommended after 2030. */
+/** ML-DSA-44 for 128-bit security level. Not recommended after 2030, as per ASD. */
 export const ml_dsa44: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[2],
   CRH_BYTES: 64,
@@ -539,7 +539,7 @@ export const ml_dsa44: SignerWithInternal = /* @__PURE__ */ getDilithium({
   XOF256,
 });
 
-/** ML-DSA-65 for 192-bit security level. As per ASD, not recommended after 2030. */
+/** ML-DSA-65 for 192-bit security level. Not recommended after 2030, as per ASD. */
 export const ml_dsa65: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[3],
   CRH_BYTES: 64,
@@ -549,7 +549,7 @@ export const ml_dsa65: SignerWithInternal = /* @__PURE__ */ getDilithium({
   XOF256,
 });
 
-/** ML-DSA-87 for 256-bit security level. As per ASD, OK after 2030. */
+/** ML-DSA-87 for 256-bit security level. OK after 2030, as per ASD. */
 export const ml_dsa87: SignerWithInternal = /* @__PURE__ */ getDilithium({
   ...PARAMS[5],
   CRH_BYTES: 64,

src/ml-kem.ts

@@ -1,6 +1,6 @@
 /**
- * Module Lattice-based Key Encapsulation Mechanism (ML-KEM). A.k.a. CRYSTALS-Kyber.
- * FIPS-203 is implemented.
+ * ML-KEM: Module Lattice-based Key Encapsulation Mechanism from
+ * [FIPS-203](https://csrc.nist.gov/pubs/fips/203/ipd). A.k.a. CRYSTALS-Kyber.
  *
  * Key encapsulation is similar to DH / ECDH (think X25519), with important differences:
  * * Unlike in ECDH, we can't verify if it was "Bob" who've sent the shared secret
@@ -345,19 +345,19 @@ const opts = {
   PRF: shakePRF,
 };
 
-/** ML-KEM-512 for 128-bit security level. As per ASD, not recommended after 2030. */
+/** ML-KEM-512 for 128-bit security level. Not recommended after 2030, as per ASD. */
 export const ml_kem512: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[512],
 });
 
-/** ML-KEM-768, for 192-bit security level. As per ASD, not recommended after 2030. */
+/** ML-KEM-768, for 192-bit security level. Not recommended after 2030, as per ASD. */
 export const ml_kem768: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[768],
 });
 
-/** ML-KEM-1024 for 256-bit security level. As per ASD, OK after 2030. */
+/** ML-KEM-1024 for 256-bit security level. OK after 2030, as per ASD. */
 export const ml_kem1024: KEM = /* @__PURE__ */ createKyber({
   ...opts,
   ...PARAMS[1024],

src/slh-dsa.ts

@@ -1,6 +1,6 @@
 /**
- * StateLess Hash-based Digital Signature Standard (SLH-DSA). A.k.a. Sphincs+.
- * FIPS-205 (spec v3.1) is implemented.
+ * SLH-DSA: StateLess Hash-based Digital Signature Standard from
+ * [FIPS-205](https://csrc.nist.gov/pubs/fips/205/ipd). A.k.a. Sphincs+ v3.1.
  *
  * There are many different kinds of SLH, but basically `sha2` / `shake` indicate internal hash,
  * `128` / `192` / `256` indicate security level, and `s` /`f` indicate trade-off (Small / Fast).

src/utils.ts

@@ -18,6 +18,7 @@ export function equalBytes(a: Uint8Array, b: Uint8Array): boolean {
   return diff === 0;
 }
 
+/** Generic interface for signatures. Has keygen, sign and verify. */
 export type Signer = {
   signRandBytes: number;
   keygen: (seed: Uint8Array) => {