docs: update JSDoc to use more link syntax

panva · Sep 15, 2024 · 34ad4d5 · 34ad4d5
1 parent c45319e
commit 34ad4d5
Show file tree

Hide file tree

Showing 30 changed files with 107 additions and 103 deletions.
diff --git a/docs/functions/key_export.exportPKCS8.md b/docs/functions/key_export.exportPKCS8.md
@@ -8,8 +8,8 @@ Support from the community to continue maintaining and improving this module is
 
 ▸ **exportPKCS8**(`key`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`string`\>
 
-Exports a runtime-specific private key representation (KeyObject or CryptoKey) to a PEM-encoded
-PKCS8 string format.
+Exports a runtime-specific private key representation ([KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) or [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey)) to
+a PEM-encoded PKCS8 string format.
 
 This function is exported (as a named export) from the main `'jose'` module entry point as well
 as from its subpath export `'jose/key/export'`.

diff --git a/docs/functions/key_export.exportSPKI.md b/docs/functions/key_export.exportSPKI.md
@@ -8,8 +8,8 @@ Support from the community to continue maintaining and improving this module is
 
 ▸ **exportSPKI**(`key`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`string`\>
 
-Exports a runtime-specific public key representation (KeyObject or CryptoKey) to a PEM-encoded
-SPKI string format.
+Exports a runtime-specific public key representation ([KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) or [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey)) to
+a PEM-encoded SPKI string format.
 
 This function is exported (as a named export) from the main `'jose'` module entry point as well
 as from its subpath export `'jose/key/export'`.

diff --git a/docs/functions/key_import.importJWK.md b/docs/functions/key_import.importJWK.md
@@ -12,7 +12,7 @@ Imports a JWK to a runtime-specific key representation (KeyLike). Either the JWK
 (Algorithm) Parameter, or the optional "alg" argument, must be present.
 
 Note: When the runtime is using [Web Cryptography API](https://w3c.github.io/webcrypto/) the
-jwk parameters "use", "key_ops", and "ext" are also used in the resulting `CryptoKey`.
+jwk parameters "use", "key_ops", and "ext" are also used in the resulting [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey).
 
 This function is exported (as a named export) from the main `'jose'` module entry point as well
 as from its subpath export `'jose/key/import'`.

diff --git a/docs/functions/key_import.importPKCS8.md b/docs/functions/key_import.importPKCS8.md
@@ -8,8 +8,8 @@ Support from the community to continue maintaining and improving this module is
 
 ▸ **importPKCS8**\<`KeyLikeType`\>(`pkcs8`, `alg`, `options?`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`KeyLikeType`\>
 
-Imports a PEM-encoded PKCS#8 string as a runtime-specific private key representation (KeyObject
-or CryptoKey).
+Imports a PEM-encoded PKCS#8 string as a runtime-specific private key representation
+([KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) or [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey)).
 
 Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
 [Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption

diff --git a/docs/functions/key_import.importSPKI.md b/docs/functions/key_import.importSPKI.md
@@ -8,8 +8,8 @@ Support from the community to continue maintaining and improving this module is
 
 ▸ **importSPKI**\<`KeyLikeType`\>(`spki`, `alg`, `options?`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`KeyLikeType`\>
 
-Imports a PEM-encoded SPKI string as a runtime-specific public key representation (KeyObject or
-CryptoKey).
+Imports a PEM-encoded SPKI string as a runtime-specific public key representation
+([KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) or [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey)).
 
 Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
 [Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption

diff --git a/docs/functions/key_import.importX509.md b/docs/functions/key_import.importX509.md
@@ -9,7 +9,7 @@ Support from the community to continue maintaining and improving this module is
 ▸ **importX509**\<`KeyLikeType`\>(`x509`, `alg`, `options?`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`KeyLikeType`\>
 
 Imports the SPKI from an X.509 string certificate as a runtime-specific public key representation
-(KeyObject or CryptoKey).
+([KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) or [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey)).
 
 Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
 [Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption

diff --git a/docs/interfaces/jws_compact_verify.CompactVerifyGetKey.md b/docs/interfaces/jws_compact_verify.CompactVerifyGetKey.md
@@ -11,7 +11,7 @@ verified at the time of this function call.
 
 **`See`**
 
-[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md) to verify using a remote JSON Web Key Set.
 
 ## Callable
 

diff --git a/docs/interfaces/jws_flattened_verify.FlattenedVerifyGetKey.md b/docs/interfaces/jws_flattened_verify.FlattenedVerifyGetKey.md
@@ -11,7 +11,7 @@ verified at the time of this function call.
 
 **`See`**
 
-[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md) to verify using a remote JSON Web Key Set.
 
 ## Callable
 

diff --git a/docs/interfaces/jws_general_verify.GeneralVerifyGetKey.md b/docs/interfaces/jws_general_verify.GeneralVerifyGetKey.md
@@ -11,7 +11,7 @@ verified at the time of this function call.
 
 **`See`**
 
-[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md) to verify using a remote JSON Web Key Set.
 
 ## Callable
 

diff --git a/docs/interfaces/jwt_verify.JWTVerifyGetKey.md b/docs/interfaces/jwt_verify.JWTVerifyGetKey.md
@@ -11,7 +11,7 @@ the time of this function call.
 
 **`See`**
 
-[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+[createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md) to verify using a remote JSON Web Key Set.
 
 ## Callable
 

diff --git a/docs/interfaces/key_generate_key_pair.GenerateKeyPairOptions.md b/docs/interfaces/key_generate_key_pair.GenerateKeyPairOptions.md
@@ -30,8 +30,7 @@ ___
 • `Optional` **extractable**: `boolean`
 
 (Only effective in Web Crypto API runtimes) The value to use as
-[SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
-`extractable` argument. Default is false.
+[SubtleCrypto.generateKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey) `extractable` argument. Default is false.
 
 **`Example`**
 

diff --git a/docs/interfaces/key_generate_secret.GenerateSecretOptions.md b/docs/interfaces/key_generate_secret.GenerateSecretOptions.md
@@ -19,5 +19,4 @@ Support from the community to continue maintaining and improving this module is
 • `Optional` **extractable**: `boolean`
 
 (Only effective in Web Crypto API runtimes) The value to use as
-[SubtleCrypto.generateKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey)
-`extractable` argument. Default is false.
+[SubtleCrypto.generateKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey) `extractable` argument. Default is false.
diff --git a/docs/interfaces/key_import.PEMImportOptions.md b/docs/interfaces/key_import.PEMImportOptions.md
@@ -18,6 +18,5 @@ Support from the community to continue maintaining and improving this module is
 
 • `Optional` **extractable**: `boolean`
 
-(Only effective in Web Crypto API runtimes) The value to use as
-[SubtleCrypto.importKey()](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
+(Only effective in Web Crypto API runtimes) The value to use as [SubtleCrypto.importKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/importKey)
 `extractable` argument. Default is false.
diff --git a/docs/interfaces/types.CompactJWSHeaderParameters.md b/docs/interfaces/types.CompactJWSHeaderParameters.md
@@ -34,7 +34,7 @@ JWS "alg" (Algorithm) Header Parameter
 
 **`See`**
 
-[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg).
+[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg)
 
 ___
 

diff --git a/docs/interfaces/types.FlattenedJWSInput.md b/docs/interfaces/types.FlattenedJWSInput.md
@@ -6,8 +6,8 @@ Support from the community to continue maintaining and improving this module is
 
 ---
 
-Flattened JWS definition for verify function inputs, allows payload as Uint8Array for detached
-signature validation.
+Flattened JWS definition for verify function inputs, allows payload as [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) for
+detached signature validation.
 
 ## Table of contents
 
@@ -25,7 +25,7 @@ signature validation.
 • **payload**: `string` \| [`Uint8Array`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array )
 
 The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When RFC7797
-"b64": false is used the value passed may also be a Uint8Array.
+"b64": false is used the value passed may also be a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
 
 ___
 

diff --git a/docs/interfaces/types.GeneralJWSInput.md b/docs/interfaces/types.GeneralJWSInput.md
@@ -6,8 +6,8 @@ Support from the community to continue maintaining and improving this module is
 
 ---
 
-General JWS definition for verify function inputs, allows payload as Uint8Array for detached
-signature validation.
+General JWS definition for verify function inputs, allows payload as [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) for
+detached signature validation.
 
 ## Table of contents
 
@@ -24,7 +24,7 @@ signature validation.
 
 The "payload" member MUST be present and contain the value BASE64URL(JWS Payload). When when
 JWS Unencoded Payload ([RFC7797](https://www.rfc-editor.org/rfc/rfc7797)) "b64": false is
-used the value passed may also be a Uint8Array.
+used the value passed may also be a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
 
 ___
 

diff --git a/docs/interfaces/types.JWSHeaderParameters.md b/docs/interfaces/types.JWSHeaderParameters.md
@@ -34,7 +34,7 @@ JWS "alg" (Algorithm) Header Parameter
 
 **`See`**
 
-[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg).
+[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg)
 
 ___
 

diff --git a/docs/interfaces/types.JWTHeaderParameters.md b/docs/interfaces/types.JWTHeaderParameters.md
@@ -34,7 +34,7 @@ JWS "alg" (Algorithm) Header Parameter
 
 **`See`**
 
-[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg).
+[Algorithm Key Requirements](https://github.com/panva/jose/issues/210#jws-alg)
 
 ___
 

diff --git a/docs/types/types.KeyLike.md b/docs/types/types.KeyLike.md
@@ -9,31 +9,24 @@ Support from the community to continue maintaining and improving this module is
 Ƭ **KeyLike**: `Object`
 
 KeyLike are runtime-specific classes representing asymmetric keys or symmetric secrets. These are
-instances of [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) and
-additionally [KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) in Node.js
-runtime.
-[Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
-instances are also accepted as symmetric secret representation only.
-
-[Key Import Functions](../modules/key_import.md) can be used to import PEM, or JWK formatted
-asymmetric keys and certificates to these runtime-specific representations.
-
-In Node.js the [Buffer](https://nodejs.org/api/buffer.html#buffer) class is a subclass of
-Uint8Array and so Buffer can be provided for symmetric secrets as well.
-
-[KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) is a representation of a
-key/secret available in the Node.js runtime. In addition to the import functions of this library
-you may use the runtime APIs
-[crypto.createPublicKey](https://nodejs.org/api/crypto.html#cryptocreatepublickeykey),
-[crypto.createPrivateKey](https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey), and
-[crypto.createSecretKey](https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding)
-to obtain a `KeyObject` from your existing key material.
-
-[CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) is a representation
-of a key/secret available in the Browser and Web-interoperable runtimes. In addition to the
-import functions of this library you may use the
-[SubtleCrypto.importKey](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey)
-API to obtain a CryptoKey from your existing key material.
+instances of [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) and additionally [KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) in Node.js runtime.
+[Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instances are also accepted as symmetric secret representation only.
+
+[Key Import Functions](../modules/key_import.md) can be used to import PEM, or JWK formatted asymmetric
+keys and certificates to these runtime-specific representations.
+
+In Node.js the [Buffer](https://nodejs.org/api/buffer.html#class-buffer) class is a subclass of [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) and so [Buffer](https://nodejs.org/api/buffer.html#class-buffer) can
+be provided for symmetric secrets as well.
+
+[KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) is a representation of a key/secret available in the Node.js runtime. In
+addition to the import functions of this library you may use the runtime APIs
+[createPublicKey](https://nodejs.org/api/crypto.html#cryptocreatepublickeykey), [createPrivateKey](https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey), and [createSecretKey](https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding) to obtain a
+[KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) from your existing key material.
+
+[CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) is a representation of a key/secret available in the Browser and
+Web-interoperable runtimes. In addition to the import functions of this library you may use the
+[SubtleCrypto.importKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/importKey) API to obtain a [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) from your existing key
+material.
 
 **`Example`**
 

diff --git a/patches/typedoc-plugin-mdn-links+3.2.12.patch b/patches/typedoc-plugin-mdn-links+3.2.12.patch
@@ -0,0 +1,24 @@
+diff --git a/node_modules/typedoc-plugin-mdn-links/data/web-api.json b/node_modules/typedoc-plugin-mdn-links/data/web-api.json
+index 3e76956..42907af 100644
+--- a/node_modules/typedoc-plugin-mdn-links/data/web-api.json
++++ b/node_modules/typedoc-plugin-mdn-links/data/web-api.json
+@@ -1,4 +1,19 @@
+ {
++	"createPublicKey": {
++		"url": "https://nodejs.org/api/crypto.html#cryptocreatepublickeykey"
++	},
++	"createPrivateKey": {
++		"url": "https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey"
++	},
++	"createSecretKey": {
++		"url": "https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding"
++	},
++	"KeyObject": {
++		"url": "https://nodejs.org/api/crypto.html#class-keyobject"
++	},
++	"Buffer": {
++		"url": "https://nodejs.org/api/buffer.html#class-buffer"
++	},
+ 	"ANGLE_instanced_arrays": {
+ 		"url": "https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays",
+ 		"inst": {
diff --git a/src/jws/compact/verify.ts b/src/jws/compact/verify.ts
@@ -16,7 +16,7 @@ import type {
  * Interface for Compact JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+ * @see {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} to verify using a remote JSON Web Key Set.
  */
 export interface CompactVerifyGetKey
   extends GenericGetKeyFunction<

diff --git a/src/jws/flattened/verify.ts b/src/jws/flattened/verify.ts
@@ -26,7 +26,7 @@ import { importJWK } from '../../key/import.js'
  * Interface for Flattened JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+ * @see {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} to verify using a remote JSON Web Key Set.
  */
 export interface FlattenedVerifyGetKey
   extends GenericGetKeyFunction<

diff --git a/src/jws/general/verify.ts b/src/jws/general/verify.ts
@@ -17,7 +17,7 @@ import isObject from '../../lib/is_object.js'
  * Interface for General JWS Verification dynamic key resolution. No token components have been
  * verified at the time of this function call.
  *
- * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+ * @see {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} to verify using a remote JSON Web Key Set.
  */
 export interface GeneralVerifyGetKey
   extends GenericGetKeyFunction<

diff --git a/src/jwt/verify.ts b/src/jwt/verify.ts
@@ -21,7 +21,7 @@ export interface JWTVerifyOptions extends VerifyOptions, JWTClaimVerificationOpt
  * Interface for JWT Verification dynamic key resolution. No token components have been verified at
  * the time of this function call.
  *
- * @see [createRemoteJWKSet](../functions/jwks_remote.createRemoteJWKSet.md#function-createremotejwkset) to verify using a remote JSON Web Key Set.
+ * @see {@link jwks/remote.createRemoteJWKSet createRemoteJWKSet} to verify using a remote JSON Web Key Set.
  */
 export interface JWTVerifyGetKey
   extends GenericGetKeyFunction<

diff --git a/src/key/export.ts b/src/key/export.ts
@@ -5,8 +5,8 @@ import keyToJWK from '../runtime/key_to_jwk.js'
 import type { JWK, KeyLike } from '../types.d'
 
 /**
- * Exports a runtime-specific public key representation (KeyObject or CryptoKey) to a PEM-encoded
- * SPKI string format.
+ * Exports a runtime-specific public key representation ({@link !KeyObject} or {@link !CryptoKey}) to
+ * a PEM-encoded SPKI string format.
  *
  * This function is exported (as a named export) from the main `'jose'` module entry point as well
  * as from its subpath export `'jose/key/export'`.
@@ -26,8 +26,8 @@ export async function exportSPKI(key: KeyLike): Promise<string> {
 }
 
 /**
- * Exports a runtime-specific private key representation (KeyObject or CryptoKey) to a PEM-encoded
- * PKCS8 string format.
+ * Exports a runtime-specific private key representation ({@link !KeyObject} or {@link !CryptoKey}) to
+ * a PEM-encoded PKCS8 string format.
  *
  * This function is exported (as a named export) from the main `'jose'` module entry point as well
  * as from its subpath export `'jose/key/export'`.

diff --git a/src/key/generate_key_pair.ts b/src/key/generate_key_pair.ts
@@ -25,8 +25,7 @@ export interface GenerateKeyPairOptions {
 
   /**
    * (Only effective in Web Crypto API runtimes) The value to use as
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey SubtleCrypto.generateKey()}
-   * `extractable` argument. Default is false.
+   * {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false.
    *
    * @example
    *

diff --git a/src/key/generate_secret.ts b/src/key/generate_secret.ts
@@ -5,8 +5,7 @@ import type { KeyLike } from '../types.d'
 export interface GenerateSecretOptions {
   /**
    * (Only effective in Web Crypto API runtimes) The value to use as
-   * {@link https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey SubtleCrypto.generateKey()}
-   * `extractable` argument. Default is false.
+   * {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false.
    */
   extractable?: boolean
 }