Merge pull request #1993 from o1-labs/2025-01-typdoc-errors-1

Resolve documentation signature mismatches

Author: 45930

src/lib/mina/fetch.ts

@@ -129,7 +129,6 @@ function setMinaGraphqlFallbackEndpoints(graphqlEndpoints: string[]) {
 /**
  * Sets up a GraphQL endpoint to be used for fetching information from an Archive Node.
  *
- * @param A GraphQL endpoint.
  */
 function setArchiveGraphqlEndpoint(graphqlEndpoint: string) {
   if (!checkForValidUrl(graphqlEndpoint)) {
@@ -170,8 +169,9 @@ function setLightnetAccountManagerEndpoint(endpoint: string) {
  * If an error is returned by the specified endpoint, an error is thrown. Otherwise,
  * the data is returned.
  *
- * @param publicKey The specified publicKey to get account information on
- * @param tokenId The specified tokenId to get account information on
+ * @param accountInfo The public key and token id of the account to fetch
+ * @param accountInfo.publicKey The specified publicKey to get account information on
+ * @param accountInfo.tokenId The specified tokenId to get account information on
  * @param graphqlEndpoint The graphql endpoint to fetch from
  * @param config An object that exposes an additional timeout option
  * @returns zkapp information on the specified account or an error is thrown
@@ -632,7 +632,6 @@ function sendZkapp(
 
 /**
  * Asynchronously fetches event data for an account from the Mina Archive Node GraphQL API.
- * @async
  * @param accountInfo - The account information object.
  * @param accountInfo.publicKey - The account public key.
  * @param [accountInfo.tokenId] - The optional token ID for the account.

src/lib/mina/zkapp.ts

@@ -1039,7 +1039,6 @@ super.init();
 
   /**
    * Asynchronously fetches events emitted by this {@link SmartContract} and returns an array of events with their corresponding types.
-   * @async
    * @param [start=UInt32.from(0)] - The start height of the events to fetch.
    * @param end - The end height of the events to fetch. If not provided, fetches events up to the latest height.
    * @returns A promise that resolves to an array of objects, each containing the event type and event data for the specified range.

src/lib/provable/field.ts

@@ -202,8 +202,8 @@ class Field {
    *
    * **Important**: If an assertion fails, the code throws an error.
    *
-   * @param value - the "field-like" value to compare & assert with this {@link Field}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertEquals(y: Field | bigint | number | string, message?: string) {
     try {
@@ -243,7 +243,7 @@ class Field {
    * sum.sub(Field(-7)).assertEquals(x);
    * ```
    *
-   * @param value - a "field-like" value to add to the {@link Field}.
+   * @param y - a "field-like" value to add to the {@link Field}.
    *
    * @return A {@link Field} element equivalent to the modular addition of the two value.
    */
@@ -307,7 +307,7 @@ class Field {
    * difference.add(Field(2)).assertEquals(x);
    * ```
    *
-   * @param value - a "field-like" value to subtract from the {@link Field}.
+   * @param y - a "field-like" value to subtract from the {@link Field}.
    *
    * @return A {@link Field} element equivalent to the modular difference of the two value.
    */
@@ -351,7 +351,7 @@ class Field {
    * product.assertEquals(Field(15));
    * ```
    *
-   * @param value - a "field-like" value to multiply with the {@link Field}.
+   * @param y - a "field-like" value to multiply with the {@link Field}.
    *
    * @return A {@link Field} element equivalent to the modular difference of the two value.
    */
@@ -435,7 +435,7 @@ class Field {
    * quotient.mul(y).assertEquals(x);
    * ```
    *
-   * @param value - a "field-like" value to divide with the {@link Field}.
+   * @param y - a "field-like" value to divide with the {@link Field}.
    *
    * @return A {@link Field} element equivalent to the modular division of the two value.
    */
@@ -515,7 +515,7 @@ class Field {
    * Field(5).equals(5).assertEquals(Bool(true));
    * ```
    *
-   * @param value - the "field-like" value to compare with this {@link Field}.
+   * @param y - the "field-like" value to compare with this {@link Field}.
    *
    * @return A {@link Bool} representing if this {@link Field} is equal another "field-like" value.
    */
@@ -564,7 +564,7 @@ class Field {
    * let isFalse = Field(1).div(3).lessThan(Field(1).div(2)); // in fact, 1/3 > 1/2
    * ```
    *
-   * @param value - the "field-like" value to compare with this {@link Field}.
+   * @param y - the "field-like" value to compare with this {@link Field}.
    *
    * @return A {@link Bool} representing if this {@link Field} is less than another "field-like" value.
    */
@@ -591,7 +591,7 @@ class Field {
    * let isFalse = Field(1).div(3).lessThanOrEqual(Field(1).div(2)); // in fact, 1/3 > 1/2
    * ```
    *
-   * @param value - the "field-like" value to compare with this {@link Field}.
+   * @param y - the "field-like" value to compare with this {@link Field}.
    *
    * @return A {@link Bool} representing if this {@link Field} is less than or equal another "field-like" value.
    */
@@ -618,7 +618,7 @@ class Field {
    * let isFalse = Field(1).div(2).greaterThan(Field(1).div(3); // in fact, 1/3 > 1/2
    * ```
    *
-   * @param value - the "field-like" value to compare with this {@link Field}.
+   * @param y - the "field-like" value to compare with this {@link Field}.
    *
    * @return A {@link Bool} representing if this {@link Field} is greater than another "field-like" value.
    */
@@ -642,7 +642,7 @@ class Field {
    * let isFalse = Field(1).div(2).greaterThanOrEqual(Field(1).div(3); // in fact, 1/3 > 1/2
    * ```
    *
-   * @param value - the "field-like" value to compare with this {@link Field}.
+   * @param y - the "field-like" value to compare with this {@link Field}.
    *
    * @return A {@link Bool} representing if this {@link Field} is greater than or equal another "field-like" value.
    */
@@ -658,8 +658,8 @@ class Field {
    *
    * **Important**: If an assertion fails, the code throws an error.
    *
-   * @param value - the "field-like" value to compare & assert with this {@link Field}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertLessThan(y: Field | bigint | number | string, message?: string) {
     try {
@@ -683,8 +683,8 @@ class Field {
    *
    * **Important**: If an assertion fails, the code throws an error.
    *
-   * @param value - the "field-like" value to compare & assert with this {@link Field}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertLessThanOrEqual(y: Field | bigint | number | string, message?: string) {
     try {
@@ -708,8 +708,8 @@ class Field {
    *
    * **Important**: If an assertion fails, the code throws an error.
    *
-   * @param value - the "field-like" value to compare & assert with this {@link Field}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertGreaterThan(y: Field | bigint | number | string, message?: string) {
     Field.from(y).assertLessThan(this, message);
@@ -723,8 +723,8 @@ class Field {
    *
    * **Important**: If an assertion fails, the code throws an error.
    *
-   * @param value - the "field-like" value to compare & assert with this {@link Field}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertGreaterThanOrEqual(
     y: Field | bigint | number | string,
@@ -738,6 +738,9 @@ class Field {
    *
    * Note: This uses fewer constraints than `x.equals(y).assertFalse()`.
    *
+   * @param y - the "field-like" value to compare & assert with this {@link Field}.
+   * @param message - a string error message to print if the assertion fails, optional.
+   *
    * @example
    * ```ts
    * x.assertNotEquals(0, "expect x to be non-zero");
@@ -775,7 +778,7 @@ class Field {
    *
    * If the assertion fails, the code throws an error.
    *
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertBool(message?: string) {
     try {
@@ -834,11 +837,11 @@ class Field {
    *
    * The method throws if the given bits do not fit in a single Field element. In this case, no more than 254 bits are allowed because some 255 bit integers do not fit into a single Field element.
    *
-   * **Important**: If the given `bytes` array is an array of `booleans` or {@link Bool} elements that all are `constant`, the resulting {@link Field} element will be a constant as well. Or else, if the given array is a mixture of constants and variables of {@link Bool} type, the resulting {@link Field} will be a variable as well.
+   * **Important**: If the given `bits` array is an array of `booleans` or {@link Bool} elements that all are `constant`, the resulting {@link Field} element will be a constant as well. Or else, if the given array is a mixture of constants and variables of {@link Bool} type, the resulting {@link Field} will be a variable as well.
    *
-   * @param bytes - An array of {@link Bool} or `boolean` type.
+   * @param bits - An array of {@link Bool} or `boolean` type.
    *
-   * @return A {@link Field} element matching the [little endian binary representation](https://en.wikipedia.org/wiki/Endianness) of the given `bytes` array.
+   * @return A {@link Field} element matching the [little endian binary representation](https://en.wikipedia.org/wiki/Endianness) of the given `bits` array.
    */
   static fromBits(bits: (Bool | boolean)[]) {
     const length = bits.length;
@@ -909,16 +912,14 @@ class Field {
    *
    * @return A {@link Field} array of length 1 created from this {@link Field}.
    */
-  static toFields(x: Field) {
-    return [x];
+  static toFields(value: Field) {
+    return [value];
   }
 
   /**
    * This function is the implementation of {@link Provable.toAuxiliary} for the {@link Field} type.
    *
    * As the primitive {@link Field} type has no auxiliary data associated with it, this function will always return an empty array.
-   *
-   * @param value - The {@link Field} element to get the auxiliary data of, optional. If not provided, the function returns an empty array.
    */
   static toAuxiliary(): [] {
     return [];
@@ -960,8 +961,6 @@ class Field {
    * This function is the implementation of {@link Provable.check} in {@link Field} type.
    *
    * As any field element can be a {@link Field}, this function does not create any assertions, so it does nothing.
-   *
-   * @param value - the {@link Field} element to check.
    */
   static check() {}
 
@@ -1044,16 +1043,16 @@ class Field {
    *
    * @return A string equivalent to the JSON representation of the given {@link Field}.
    */
-  static toJSON(x: Field) {
-    return x.toJSON();
+  static toJSON(value: Field) {
+    return value.toJSON();
   }
 
   /**
    * Deserialize a JSON string containing a "field-like" value into a {@link Field} element.
    *
    * **Warning**: This operation does _not_ affect the circuit and can't be used to prove anything about the string representation of the {@link Field}.
    *
-   * @param value - the "field-like" value to coerce the {@link Field} from.
+   * @param json - the "field-like" value to coerce the {@link Field} from.
    *
    * @return A {@link Field} coerced from the given JSON string.
    */
@@ -1071,8 +1070,8 @@ class Field {
    * @return An object where the `fields` key is a {@link Field} array of length 1 created from this {@link Field}.
    *
    */
-  static toInput(x: Field) {
-    return { fields: [x] };
+  static toInput(value: Field) {
+    return { fields: [value] };
   }
 
   // Binable<Field>
@@ -1086,8 +1085,8 @@ class Field {
    * @return An array of digits equal to the [little-endian](https://en.wikipedia.org/wiki/Endianness) byte order of the given {@link Field} element.
    *
    */
-  static toBytes(x: Field) {
-    return FieldBinable.toBytes(x);
+  static toBytes(value: Field) {
+    return FieldBinable.toBytes(value);
   }
 
   /**

src/lib/provable/int.ts

@@ -302,8 +302,6 @@ class UInt64 extends CircuitValue {
    *
    * ```
    *
-   * @param a - The value to apply NOT to.
-   *
    */
   not() {
     return new UInt64(Bitwise.not(this.value, UInt64.NUM_BITS, false).value);
@@ -776,7 +774,6 @@ class UInt32 extends CircuitValue {
    * // 11111111111111111111111111111010
    * ```
    *
-   * @param a - The value to apply NOT to.
    */
   not() {
     return new UInt32(Bitwise.not(this.value, UInt32.NUM_BITS, false).value);
@@ -1147,7 +1144,7 @@ class Int64 extends CircuitValue implements BalanceChange {
    * This is the recommended way to create Int64 instances.
    *
    * @param magnitude - The magnitude of the integer as a UInt64
-   * @param sgn - The sign of the integer.
+   * @param sign - The sign of the integer.
    * @returns A new Int64 instance with a canonical representation.
    *
    * @example
@@ -1654,7 +1651,7 @@ class UInt8 extends Struct({
    * **Important**: If an assertion fails, the code throws an error.
    *
    * @param y - the {@link UInt8} value to compare & assert with this {@link UInt8}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertLessThan(y: UInt8 | bigint | number, message?: string) {
     let y_ = UInt8.from(y);
@@ -1679,7 +1676,7 @@ class UInt8 extends Struct({
    * **Important**: If an assertion fails, the code throws an error.
    *
    * @param y - the {@link UInt8} value to compare & assert with this {@link UInt8}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertLessThanOrEqual(y: UInt8 | bigint | number, message?: string) {
     let y_ = UInt8.from(y);
@@ -1736,7 +1733,7 @@ class UInt8 extends Struct({
    * **Important**: If an assertion fails, the code throws an error.
    *
    * @param y - the {@link UInt8} value to compare & assert with this {@link UInt8}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertGreaterThan(y: UInt8 | bigint | number, message?: string) {
     UInt8.from(y).assertLessThan(this, message);
@@ -1748,7 +1745,7 @@ class UInt8 extends Struct({
    * **Important**: If an assertion fails, the code throws an error.
    *
    * @param y - the {@link UInt8} value to compare & assert with this {@link UInt8}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertGreaterThanOrEqual(y: UInt8, message?: string) {
     UInt8.from(y).assertLessThanOrEqual(this, message);
@@ -1760,7 +1757,7 @@ class UInt8 extends Struct({
    * **Important**: If an assertion fails, the code throws an error.
    *
    * @param y - the {@link UInt8} value to compare & assert with this {@link UInt8}.
-   * @param message? - a string error message to print if the assertion fails, optional.
+   * @param message - a string error message to print if the assertion fails, optional.
    */
   assertEquals(y: UInt8 | bigint | number, message?: string) {
     let y_ = UInt8.from(y);

src/lib/provable/merkle-tree.ts

@@ -68,8 +68,8 @@ class MerkleTree {
    * @param index Index of the leaf.
    * @returns The data of the leaf.
    */
-  getLeaf(key: bigint) {
-    return this.getNode(0, key);
+  getLeaf(index: bigint) {
+    return this.getNode(0, index);
   }
 
   /**

src/lib/provable/scalar.ts

@@ -244,8 +244,8 @@ class Scalar implements ShiftedScalar {
    * @return An object where the `fields` key is a {@link Field} array of length 1 created from this {@link Field}.
    *
    */
-  static toInput(x: Scalar): HashInput {
-    return { fields: [x.high254], packed: [[x.lowBit.toField(), 1]] };
+  static toInput(value: Scalar): HashInput {
+    return { fields: [value.high254], packed: [[value.lowBit.toField(), 1]] };
   }
 
   /**

src/lib/provable/types/struct.ts

@@ -71,6 +71,7 @@ type AnyConstructor = Constructor<any>;
  * These composite types can be passed in as arguments to smart contract methods, used for on-chain state variables
  * or as event / action types.
  *
+ * @example
  * Here's an example of creating a "Voter" struct, which holds a public key and a collection of votes on 3 different proposals:
  * ```ts
  * let Vote = { hasVoted: Bool, inFavor: Bool };
@@ -131,10 +132,9 @@ type AnyConstructor = Constructor<any>;
  * Again, it's important to note that this doesn't enable you to prove anything about the `fullName` string.
  * From the circuit point of view, it simply doesn't exist!
  *
- * @note Ensure you do not use or extend `Struct` as a type directly. Instead, always call it as a function to construct a type. `Struct` is not a valid provable type itself, types created with `Struct(...)` are.
+ * **Note**: Ensure you do not use or extend `Struct` as a type directly. Instead, always call it as a function to construct a type. `Struct` is not a valid provable type itself, types created with `Struct(...)` are.
  *
  * @param type Object specifying the layout of the `Struct`
- * @param options Advanced option which allows you to force a certain order of object keys
  * @returns Class which you can extend
  */
 function Struct<

typedoc.json

@@ -14,6 +14,9 @@
     "src/lib/provable/+(core|test)/**/*",
     "src/**/*(test|unit-test).ts",
   ],
+  "validation": {
+    "notExported": false, // Allows us to reference types and classes that are not documented from types and classes that are documented
+  },
   "entryPoints": [
     "src/index.ts",
     "src/lib/provable/field.ts",