ts: Add documentation for all builder methods (#3295)

ts/packages/anchor/src/program/namespace/methods.ts

@@ -230,6 +230,8 @@ export class MethodsBuilder<
    *
    * See {@link accounts} and {@link accountsPartial} methods for automatically
    * resolving accounts.
+   *
+   * @param accounts instruction accounts
    */
   public accountsStrict(accounts: Accounts<A>) {
     this._resolveAccounts = false;
@@ -237,16 +239,40 @@ export class MethodsBuilder<
     return this;
   }
 
+  /**
+   * Set instruction signers.
+   *
+   * Note that calling this method appends the given signers to the existing
+   * signers (instead of overriding them).
+   *
+   * @param signers signers to append
+   */
   public signers(signers: Array<Signer>) {
     this._signers = this._signers.concat(signers);
     return this;
   }
 
+  /**
+   * Set remaining accounts.
+   *
+   * Note that calling this method appends the given accounts to the existing
+   * remaining accounts (instead of overriding them).
+   *
+   * @param accounts remaining accounts
+   */
   public remainingAccounts(accounts: Array<AccountMeta>) {
     this._remainingAccounts = this._remainingAccounts.concat(accounts);
     return this;
   }
 
+  /**
+   * Set previous instructions.
+   *
+   * See {@link postInstructions} to set the post instructions instead.
+   *
+   * @param ixs instructions
+   * @param prepend whether to prepend to the existing previous instructions
+   */
   public preInstructions(ixs: Array<TransactionInstruction>, prepend = false) {
     if (prepend) {
       this._preInstructions = ixs.concat(this._preInstructions);
@@ -256,6 +282,13 @@ export class MethodsBuilder<
     return this;
   }
 
+  /**
+   * Set post instructions.
+   *
+   * See {@link preInstructions} to set the previous instructions instead.
+   *
+   * @param ixs instructions
+   */
   public postInstructions(ixs: Array<TransactionInstruction>) {
     this._postInstructions = this._postInstructions.concat(ixs);
     return this;
@@ -280,58 +313,59 @@ export class MethodsBuilder<
     return this._accounts;
   }
 
-  public async rpc(options?: ConfirmOptions): Promise<TransactionSignature> {
+  /**
+   * Create an instruction based on the current configuration.
+   *
+   * See {@link transaction} to create a transaction instead.
+   *
+   * @returns the transaction instruction
+   */
+  public async instruction(): Promise<TransactionInstruction> {
     if (this._resolveAccounts) {
       await this._accountsResolver.resolve();
     }
 
     // @ts-ignore
-    return this._rpcFn(...this._args, {
+    return this._ixFn(...this._args, {
       accounts: this._accounts,
       signers: this._signers,
       remainingAccounts: this._remainingAccounts,
       preInstructions: this._preInstructions,
       postInstructions: this._postInstructions,
-      options,
     });
   }
 
-  public async rpcAndKeys(options?: ConfirmOptions): Promise<{
-    pubkeys: InstructionAccountAddresses<IDL, I>;
-    signature: TransactionSignature;
-  }> {
-    const pubkeys = await this.pubkeys();
-    return {
-      pubkeys: pubkeys as Required<InstructionAccountAddresses<IDL, I>>,
-      signature: await this.rpc(options),
-    };
-  }
-
-  public async view(options?: ConfirmOptions): Promise<any> {
+  /**
+   * Create a transaction based on the current configuration.
+   *
+   * This method doesn't send the created transaction. Use {@link rpc} method
+   * to conveniently send an confirm the configured transaction.
+   *
+   * See {@link instruction} to only create an instruction instead.
+   *
+   * @returns the transaction
+   */
+  public async transaction(): Promise<Transaction> {
     if (this._resolveAccounts) {
       await this._accountsResolver.resolve();
     }
 
-    if (!this._viewFn) {
-      throw new Error(
-        [
-          "Method does not support views.",
-          "The instruction should return a value, and its accounts must be read-only",
-        ].join(" ")
-      );
-    }
-
     // @ts-ignore
-    return this._viewFn(...this._args, {
+    return this._txFn(...this._args, {
       accounts: this._accounts,
       signers: this._signers,
       remainingAccounts: this._remainingAccounts,
       preInstructions: this._preInstructions,
       postInstructions: this._postInstructions,
-      options,
     });
   }
 
+  /**
+   * Simulate the configured transaction.
+   *
+   * @param options confirmation options
+   * @returns the simulation response
+   */
   public async simulate(options?: ConfirmOptions): Promise<SimulateResponse> {
     if (this._resolveAccounts) {
       await this._accountsResolver.resolve();
@@ -348,52 +382,102 @@ export class MethodsBuilder<
     });
   }
 
-  public async instruction(): Promise<TransactionInstruction> {
+  /**
+   * View the configured transaction.
+   *
+   * Note that to use this method, the instruction needs to return a value and
+   * all its accounts must be read-only.
+   *
+   * @param options confirmation options
+   * @returns the return value of the instruction
+   */
+  public async view(options?: ConfirmOptions): Promise<any> {
     if (this._resolveAccounts) {
       await this._accountsResolver.resolve();
     }
 
+    if (!this._viewFn) {
+      throw new Error(
+        [
+          "Method does not support views.",
+          "The instruction should return a value, and its accounts must be read-only",
+        ].join(" ")
+      );
+    }
+
     // @ts-ignore
-    return this._ixFn(...this._args, {
+    return this._viewFn(...this._args, {
       accounts: this._accounts,
       signers: this._signers,
       remainingAccounts: this._remainingAccounts,
       preInstructions: this._preInstructions,
       postInstructions: this._postInstructions,
+      options,
     });
   }
 
   /**
-   * Convenient shortcut to get instructions and pubkeys via:
+   * Send and confirm the configured transaction.
    *
-   * ```ts
-   * const { pubkeys, instructions } = await method.prepare();
-   * ```
+   * See {@link rpcAndKeys} to both send the transaction and get the resolved
+   * account public keys.
+   *
+   * @param options confirmation options
+   * @returns the transaction signature
    */
-  public async prepare(): Promise<{
-    pubkeys: Partial<InstructionAccountAddresses<IDL, I>>;
-    instruction: TransactionInstruction;
-    signers: Signer[];
-  }> {
-    return {
-      instruction: await this.instruction(),
-      pubkeys: await this.pubkeys(),
-      signers: this._signers,
-    };
-  }
-
-  public async transaction(): Promise<Transaction> {
+  public async rpc(options?: ConfirmOptions): Promise<TransactionSignature> {
     if (this._resolveAccounts) {
       await this._accountsResolver.resolve();
     }
 
     // @ts-ignore
-    return this._txFn(...this._args, {
+    return this._rpcFn(...this._args, {
       accounts: this._accounts,
       signers: this._signers,
       remainingAccounts: this._remainingAccounts,
       preInstructions: this._preInstructions,
       postInstructions: this._postInstructions,
+      options,
     });
   }
+
+  /**
+   * Conveniently call both {@link rpc} and {@link pubkeys} methods.
+   *
+   * @param options confirmation options
+   * @returns the transaction signature and account public keys
+   */
+  public async rpcAndKeys(options?: ConfirmOptions): Promise<{
+    signature: TransactionSignature;
+    pubkeys: InstructionAccountAddresses<IDL, I>;
+  }> {
+    return {
+      signature: await this.rpc(options),
+      pubkeys: (await this.pubkeys()) as Required<
+        InstructionAccountAddresses<IDL, I>
+      >,
+    };
+  }
+
+  /**
+   * Get instruction information necessary to include the instruction inside a
+   * transaction.
+   *
+   * # Example
+   *
+   * ```ts
+   * const { instruction, signers, pubkeys } = await method.prepare();
+   * ```
+   */
+  public async prepare(): Promise<{
+    instruction: TransactionInstruction;
+    signers: Signer[];
+    pubkeys: Partial<InstructionAccountAddresses<IDL, I>>;
+  }> {
+    return {
+      instruction: await this.instruction(),
+      signers: this._signers,
+      pubkeys: await this.pubkeys(),
+    };
+  }
 }