Fix Typedoc (#2189)

The config file changes related to include paths are what fixed the
actual error. See #2190 for a proposed workflow change to detect this
kind of breakage on PRs.

I also addressed many (but not all) of the doc-generation warnings and
broken links.

apps/passport-server/src/routing/routes/pcdIssuanceRoutes.ts

@@ -26,8 +26,8 @@ export function initPCDIssuanceRoutes(
   logger("[INIT] initializing PCD issuance routes");
 
   /**
-   * If either of the {@code process.env.SERVER_RSA_PRIVATE_KEY_BASE64} or
-   * {@code process.env.SERVER_EDDSA_PRIVATE_KEY} are not initialized properly,
+   * If either of the `process.env.SERVER_RSA_PRIVATE_KEY_BASE64` or
+   * `process.env.SERVER_EDDSA_PRIVATE_KEY` are not initialized properly,
    * then this server won't have an {@link IssuanceService}. It'll continue
    * to work, except users won't get any 'issued' tickets - Devconnect,
    * Zuconnect, Zuzalu, etc.

apps/passport-server/src/services/generic-issuance/pipelines/CSVPipeline/makeMessagePCD.ts

@@ -6,7 +6,7 @@ import { traced } from "../../../telemetryService";
 /**
  * Given a CSV row uploaded by a user to a {@link CSVPipeline},
  * generates an {@link MessagePCD} containing {@link }signed
- * {@code process.env.GENERIC_ISSUANCE_EDDSA_PRIVATE_KEY}
+ * `process.env.GENERIC_ISSUANCE_EDDSA_PRIVATE_KEY`
  *
  *
  * - `title`: gets displayed in the title of the PCD

apps/passport-server/test/generic-issuance/util.ts

@@ -173,7 +173,7 @@ export function getTicketsFromFeedResponse(
 export async function requestTicketsFromPipeline(
   expectedFolder: string,
   /**
-   * Generated by {@code makeGenericIssuanceFeedUrl}.
+   * Generated by `makeGenericIssuanceFeedUrl`.
    */
   feedUrl: string,
   feedId: string,
@@ -216,7 +216,7 @@ export async function requestTicketsFromPipeline(
 export async function requestTicketsFromPipelineWithEmailPCDs(
   expectedFolder: string,
   /**
-   * Generated by {@code makeGenericIssuanceFeedUrl}.
+   * Generated by `makeGenericIssuanceFeedUrl`.
    */
   feedUrl: string,
   feedId: string,

apps/zupoll-client/src/api/prismaTypes.ts

@@ -39,7 +39,7 @@ export type Poll = {
   createdAt: Date;
   body: string;
   /**
-   * Either a string or a {@code JSON.stringify}'d {@link ObjectOption}
+   * Either a string or a `JSON.stringify`'d {@link ObjectOption}
    */
   options: string[];
   expiry: Date;

packages/lib/client-shared/src/util.ts

@@ -1,7 +1,7 @@
 import { emptyStrToUndefined } from "@pcd/util";
 
 /**
- * Settings for calling {@link gpcArtifactDownloadURL} as parsed from an
+ * Settings for calling {@link @pcd/gpc!gpcArtifactDownloadURL} as parsed from an
  * environment variable by {@link parseGPCArtifactsConfig}.
  */
 export type GPCArtifactsConfigEnv = {
@@ -15,7 +15,7 @@ export type GPCArtifactsConfigEnv = {
  * environment variable, or provides default values if not set.
  *
  * @param envConfig environment variable value for override
- * @returns config variables suitable for calling {@link gpcArtifactDownloadURL}.
+ * @returns config variables suitable for calling {@link @pcd/gpc!gpcArtifactDownloadURL}.
  * @throws if the input string isn't in the correct JSON format
  */
 export function parseGPCArtifactsConfig(

packages/lib/gpc/src/gpc.ts

@@ -148,7 +148,7 @@ export function gpcCheckProvable(
 /**
  * Performs only the preparatory steps of {@link gpcProve}, returning all of
  * the circuit-related info needed to generate a proof using the
- * {@link @pcd/gpcircuits} package, or another user-supplied proving stack.
+ * {@link "@pcd/gpcircuits"} package, or another user-supplied proving stack.
  *
  * Inputs will be fully validated for structural soundness in the same way as
  * when generating a proof.  See {@link gpcProve} for more details on inputs
@@ -192,7 +192,7 @@ export function gpcPreProve(
 
 /**
  * Performs only the post-processing steps of {@link gpcProve}, taking in a
- * proof already genereated using the {@link @pcd/gpcircuits} package, or
+ * proof already genereated using the {@link "@pcd/gpcircuits"} package, or
  * another user-supplied proving stack.  The circuit-specific outputs are
  * processed into the {@link GPCRevealedClaims} to produce the normal output
  * of {@link gpcProve}.
@@ -296,7 +296,7 @@ export async function gpcProve(
 /**
  * Performs only the preparatory steps of {@link gpcVerify}, returning all of
  * the circuit-related info needed to verify a proof using the
- * {@link @pcd/gpcircuits} package, or another user-supplied verification stack.
+ * {@link "@pcd/gpcircuits"} package, or another user-supplied verification stack.
  *
  * Inputs will be fully validated for structural soundness, but not
  * cryptographically.  See {@link gpcVerify} for more details on inputs and

packages/lib/gpc/src/gpcJSON.ts

@@ -22,8 +22,8 @@ import {
  * safe to serialize directly using `JSON.stringify`.
  *
  * This is identical to the TypeScript type except that `bigint` and
- * {@link PODValue} elements are replaced by JSON-compatible representations
- * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively.
+ * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible representations
+ * defined by {@link @pcd/pod!JSONBigInt} and {@link JSONPODValue} respectively.
  *
  * Use {@link proofConfigToJSON} and {@link proofConfigFromJSON} to convert
  * between JSON and TypeScript represenations.
@@ -49,7 +49,7 @@ export function proofConfigToJSON(config: GPCProofConfig): JSONProofConfig {
  * potentially received directly from `JSON.parse`.  See {@link JSONProofConfig}
  * for information about the format.
  *
- * @param config the JSON representation
+ * @param jsonConfig the JSON representation
  * @returns a config object
  * @throws if the config is invalid
  */
@@ -66,8 +66,9 @@ export function proofConfigFromJSON(
  * safe to serialize directly using `JSON.stringify`.
  *
  * This is identical to the TypeScript type except that `bigint` and
- * {@link PODValue} elements are replaced by JSON-compatible representations
- * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively.
+ * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible
+ * representations defined by {@link @pcd/pod!JSONBigInt} and
+ * {@link @pcd/pod!JSONPODValue} respectively.
  *
  * Use {@link boundConfigToJSON} and {@link boundConfigFromJSON} to convert
  * between JSON and TypeScript represenations.
@@ -93,7 +94,7 @@ export function boundConfigToJSON(config: GPCBoundConfig): JSONBoundConfig {
  * potentially received directly from `JSON.parse`.  See {@link JSONProofConfig}
  * for information about the format.
  *
- * @param config the JSON representation
+ * @param jsonConfig the JSON representation
  * @returns a config object
  * @throws if the config is invalid
  */
@@ -110,8 +111,8 @@ export function boundConfigFromJSON(
  * safe to serialize directly using `JSON.stringify`.
  *
  * This is identical to the TypeScript type except that `bigint` and
- * {@link PODValue} elements are replaced by JSON-compatible representations
- * defined by {@link JSONBigInt} and {@link JSONPODValue} respectively.
+ * {@link @pcd/pod!PODValue} elements are replaced by JSON-compatible representations
+ * defined by {@link @pcd/pod!JSONBigInt} and {@link JSONPODValue} respectively.
  *
  * Use {@link boundConfigToJSON} and {@link boundConfigFromJSON} to convert
  * between JSON and TypeScript represenations.
@@ -123,7 +124,7 @@ export type JSONRevealedClaims = ValibotRevealedClaims.JSONType;
  * which can be serialized directly using `JSON.stringify`.  See
  * {@link JSONRevealedClaims} for information about the format.
  *
- * @param config the config object to convert
+ * @param claims the claims object to convert
  * @returns a JSON representation
  * @throws if the config is invalid
  */
@@ -139,7 +140,7 @@ export function revealedClaimsToJSON(
  * potentially received directly from `JSON.parse`.  See
  * {@link JSONRevealedClaims} for information about the format.
  *
- * @param config the JSON representation
+ * @param jsonClaims the JSON representation
  * @returns a config object
  * @throws if the config is invalid
  */

packages/lib/gpc/src/gpcTypes.ts

@@ -6,7 +6,8 @@ import type { Groth16Proof } from "snarkjs";
 /**
  * String specifying a named entry, virtual or otherwise, in a named object, in
  * the format `objectName.entryName`.  Each of the sub-parts should be a valid
- * PODName, checked by {@link POD_NAME_REGEX} or {@link POD_VIRTUAL_NAME_REGEX}.
+ * PODName, checked by {@link @pcd/pod!POD_NAME_REGEX} or
+ * {@link POD_VIRTUAL_NAME_REGEX}.
  *
  * Examples: "ticket1.eventID", "award.$signerPublicKey"
  */
@@ -48,14 +49,21 @@ export const POD_VIRTUAL_NAME_REGEX = new RegExp(
  */
 export type PODMembershipLists = Record<PODName, PODValue[] | PODValueTuple[]>;
 
-// Single source of truth for tuple prefix (used internally).
-// This should not be a valid {@link PODName} to avoid name clashes.
+/**
+ * Single source of truth for tuple prefix (used internally).
+ * This should not be a valid {@link PODName} to avoid name clashes.
+ */
 export const TUPLE_PREFIX = "$tuple";
-type TuplePrefix = typeof TUPLE_PREFIX;
+
+/**
+ * Type representation of the tuple prefix string "$tuple".
+ */
+export type TuplePrefix = typeof TUPLE_PREFIX;
 
 /**
  * String specifying a named tuple in the format `tuple.tupleName`.
- * `tupleName` should be a valid PODName checked by {@link POD_NAME_REGEX}.
+ * `tupleName` should be a valid PODName checked by
+ * {@link @pcd/pod!POD_NAME_REGEX}.
  */
 export type TupleIdentifier = `${TuplePrefix}.${PODName}`;
 
@@ -101,7 +109,7 @@ export type GPCProofEntryConfigCommon = {
    * used to find the entry in one of the pods in {@link GPCProofInputs}.
    *
    * Comparison in the proof circuit is based on the hash produced by
-   * {@link podValueHash}.  This means values of different types can be
+   * {@link @pcd/pod!podValueHash}.  This means values of different types can be
    * considered equal if they are treated in the same way by circuits.
    *
    * If undefined, there is no equality constraint.
@@ -119,7 +127,7 @@ export type GPCProofEntryConfigCommon = {
    * find the entry in one of the pods in {@link GPCProofInputs}.
    *
    * Comparison in the proof circuit is based on the hash produced by
-   * {@link podValueHash}.  This means values of different types can be
+   * {@link @pcd/pod!podValueHash}.  This means values of different types can be
    * considered equal if they are treated in the same way by circuits.
    *
    * If undefined, there is no inequality constraint.
@@ -229,7 +237,7 @@ export type GPCProofEntryConfig = GPCProofEntryConfigCommon &
      * their identity commitment.
      *
      * Comparison in the proof circuit is based on the hash produced by
-     * {@link podValueHash}.  This means values of different types can be
+     * {@link @pcd/pod!podValueHash}.  This means values of different types can be
      * considered equal if they are treated in the same way by circuits.
      *
      * If undefined, there is no owner-related constraint on this entry.
@@ -326,7 +334,7 @@ export type GPCProofConfig = {
    * will pick the smallest supported circuit which can handle this
    * configuration.
    *
-   * See {@link ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.)
+   * See {@link "@pcd/gpcircuits"!ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.)
    */
   circuitIdentifier?: GPCIdentifier;
 
@@ -399,7 +407,7 @@ export type GPCBoundConfig = GPCProofConfig & {
    * and verifying.  Same meaning as in {@link GPCProofConfig} except here it
    * is a required field.
    *
-   * See {@link ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.)
+   * See {@link "@pcd/gpcircuits"!ProtoPODGPC.CIRCUIT_FAMILY} for supported circuits.)
    */
   circuitIdentifier: GPCIdentifier;
 };
@@ -420,13 +428,13 @@ export type GPCProof = Groth16Proof;
 export type GPCProofOwnerInputs = {
   /**
    * The owner's identity using Semaphore V3. This need not be specified if no
-   * entry has {@link isOwnerID} equal to "SemaphoreV3".
+   * entry has {@link GPCProofEntryConfig.isOwnerID} equal to "SemaphoreV3".
    */
   semaphoreV3?: IdentityV3;
 
   /**
    * The owner's identity using Semaphore V4. This need not be specified if no
-   * entry has {@link isOwnerID} equal to "SemaphoreV4".
+   * entry has {@link GPCProofEntryConfig.isOwnerID} equal to "SemaphoreV4".
    */
   semaphoreV4?: IdentityV4;
 
@@ -436,11 +444,11 @@ export type GPCProofOwnerInputs = {
    * owner's private identity.  This allows identifying duplicate proofs (e.g.
    * to avoid double spending or voting) without de-anonymizing the owner.
    *
-   * This field can be a {@link PODValue} of any type, and will be represented
+   * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented
    * in the circuit as a number or a hash as appropriate.  When the proof
    * is verified, the external nullifier is also verified (as a public input).
    *
-   * This field cannot be set if no entry is marked with {@link isOwnerID},
+   * This field cannot be set if no entry is marked with {@link GPCProofEntryConfig.isOwnerID},
    * because such a nullifier would not be cryptographically tied to anything
    * verifiable.
    */
@@ -482,7 +490,7 @@ export type GPCProofInputs = {
    * to allow identifying duplicate proofs without de-anonymizing.
    *
    * This field can be omitted if an owner is not needed for any entry
-   * an entry with {@link isOwnerID} set.
+   * an entry with {@link GPCProofEntryConfig.isOwnerID} set.
    */
   owner?: GPCProofOwnerInputs;
 
@@ -502,7 +510,7 @@ export type GPCProofInputs = {
    * avoid reuse.  Unlike a nullifier, this watermark is not cryptographically
    * tied to any specific input data.
    *
-   * This field can be a {@link PODValue} of any type, and will be represented
+   * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented
    * in the circuit as a number or a hash as appropriate.  When the proof
    * is verified, the watermark is also verified (as a public input).
    */
@@ -545,12 +553,13 @@ export type GPCRevealedObjectClaims = {
 export type GPCRevealedOwnerClaims = {
   /**
    * If this field is set, it matches the corresponding field in
-   * {@link GPCProofInputs}, and {@link nullifierHash} will also be set.  The
-   * hash is uniquely tied to this value, and to the owner's private identity.
-   * This allows identifying duplicate proofs (e.g. to avoid double spending
-   * or voting) without de-anonymizing the owner.
+   * {@link GPCProofInputs}, and {@link nullifierHashV3} or
+   * {@link nullifierHashV4} will also be set.  The hash is uniquely tied to
+   * this value, and to the owner's private identity. This allows identifying
+   * duplicate proofs (e.g. to avoid double spending or voting) without
+   * de-anonymizing the owner.
    *
-   * This field can be a {@link PODValue} of any type, and will be represented
+   * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented
    * in the circuit as a number or a hash as appropriate.  When the proof
    * is verified, the external nullifier is also verified (as a public input).
    */
@@ -621,7 +630,7 @@ export type GPCRevealedClaims = {
    * specific use case, to avoid reuse.  Unlike a nullifier, this watermark is
    * not cryptographically tied to any specific input data.
    *
-   * This field can be a {@link PODValue} of any type, and will be represented
+   * This field can be a {@link @pcd/pod!PODValue} of any type, and will be represented
    * in the circuit as a number or a hash as appropriate.  When the proof
    * is verified, the watermark is also verified (as a public input).
    */

packages/lib/gpc/src/gpcUtil.ts

@@ -311,7 +311,7 @@ function canonicalizeTupleConfig(
 
 /**
  * Checks that the input matches the proper format for an entry name, virtual or
- * ortherwise, as given by {@link POD_NAME_REGEX} and {@link
+ * ortherwise, as given by {@link @pcd/pod!POD_NAME_REGEX} and {@link
  * POD_VIRTUAL_NAME_REGEX}.
  *
  * @param name the string to check

packages/lib/gpc/tsconfig.json

@@ -1,25 +1,15 @@
 {
   "extends": "@pcd/tsconfig/ts-library.json",
   "compilerOptions": {
-    "lib": [
-      "dom"
-    ],
+    "lib": ["dom"],
     "outDir": "dist",
     "declarationDir": "dist/types",
     // Include all source files, including tests
     "rootDir": "."
   },
   // Some artifact-including packages need to import a JSON file
-  "include": [
-    "src",
-    "test",
-    "artifacts/*.json"
-  ],
-  "exclude": [
-    "dist",
-    "build",
-    "node_modules"
-  ],
+  "include": ["src", "test", "artifacts/*.json", "scripts"],
+  "exclude": ["dist", "build", "node_modules"],
   // DO NOT MODIFY MANUALLY BEYOND THIS POINT
   // References are automatically maintained by `yarn fix-references`
   "references": [

packages/lib/gpcircuits/src/proto-pod-gpc.ts

@@ -394,9 +394,9 @@ export class ProtoPODGPC {
    *
    * @param inputs full inputs (public and private)
    * @param wasmPath path to wasm file for witness generation.
-   *   See {@link artifactPaths}.
+   *   See {@link CircuitArtifactPaths}.
    * @param pkeyPath path to file containing proving key.
-   *   See {@link artifactPaths}.
+   *   See {@link CircuitArtifactPaths}.
    * @returns Groth16 proof, circuit outputs, and full set of public signals
    * (primarily for verification in tests).
    */
@@ -430,7 +430,7 @@ export class ProtoPODGPC {
    * Verify a proof for a circuit in this library.
    *
    * @param vkeyPath path to verification key as a JSON file.
-   *   See {@link artifactPaths}.
+   *   See {@link CircuitArtifactPaths}.
    * @param proof Groth16 proof.
    * @param publicInputs claimed public inputs to the circuit.
    *   See {@link filterPublicInputs}

packages/lib/gpcircuits/src/types.ts

@@ -9,8 +9,19 @@ export type CircuitSignal = `${number}` | bigint;
  * Paths to circuit artifacts (files) required for proving and verifying.
  */
 export type CircuitArtifactPaths = {
+  /**
+   * path to wasm file for witness generation.
+   */
   wasmPath: string;
+
+  /**
+   * path to JSON file containing the proving key.
+   */
   pkeyPath: string;
+
+  /**
+   * path to JSON file containing the verification key.
+   */
   vkeyPath: string;
 };