Improve documentation of RestClient, CosmWasmClient, SigningCosmWasmClient

packages/sdk/src/cosmwasmclient.ts

@@ -150,8 +150,17 @@ export class CosmWasmClient {
   private readonly codesCache = new Map<number, CodeDetails>();
   private chainId: string | undefined;
 
-  public constructor(url: string, broadcastMode = BroadcastMode.Block) {
-    this.restClient = new RestClient(url, broadcastMode);
+  /**
+   * Creates a new client to interact with a CosmWasm blockchain.
+   *
+   * This instance does a lot of caching. In order to benefit from that you should try to use one instance
+   * for the lifetime of your application. When switching backends, a new instance must be created.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
+  public constructor(apiUrl: string, broadcastMode = BroadcastMode.Block) {
+    this.restClient = new RestClient(apiUrl, broadcastMode);
   }
 
   public async getChainId(): Promise<string> {

packages/sdk/src/restclient.ts

@@ -263,17 +263,28 @@ function parseAxiosError(err: AxiosError): never {
 
 export class RestClient {
   private readonly client: AxiosInstance;
-  private readonly mode: BroadcastMode;
+  private readonly broadcastMode: BroadcastMode;
 
-  public constructor(url: string, mode = BroadcastMode.Block) {
+  /**
+   * Creates a new client to interact with a Cosmos SDK light client daemon.
+   * This class tries to be a direct mapping onto the API. Some basic decoding and normalizatin is done
+   * but things like caching are done at a higher level.
+   *
+   * When building apps, you should not need to use this class directly. If you do, this indicates a missing feature
+   * in higher level components. Feel free to raise an issue in this case.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
+  public constructor(apiUrl: string, broadcastMode = BroadcastMode.Block) {
     const headers = {
       post: { "Content-Type": "application/json" },
     };
     this.client = axios.create({
-      baseURL: url,
+      baseURL: apiUrl,
       headers: headers,
     });
-    this.mode = mode;
+    this.broadcastMode = broadcastMode;
   }
 
   public async get(path: string): Promise<RestClientResponse> {
@@ -368,7 +379,7 @@ export class RestClient {
   public async postTx(tx: StdTx): Promise<PostTxsResponse> {
     const params = {
       tx: tx,
-      mode: this.mode,
+      mode: this.broadcastMode,
     };
     const responseData = await this.post("/txs", params);
     if (!(responseData as any).txhash) {

packages/sdk/src/signingcosmwasmclient.ts

@@ -103,14 +103,26 @@ export class SigningCosmWasmClient extends CosmWasmClient {
   private readonly signCallback: SigningCallback;
   private readonly fees: FeeTable;
 
+  /**
+   * Creates a new client with signing capability to interact with a CosmWasm blockchain. This is the bigger brother of CosmWasmClient.
+   *
+   * This instance does a lot of caching. In order to benefit from that you should try to use one instance
+   * for the lifetime of your application. When switching backends, a new instance must be created.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param senderAddress The address that will sign and send transactions using this instance
+   * @param signCallback An asynchonous callback to create a signature for a given transaction. This can be implemented using secure key stores that require user interaction.
+   * @param customFees The fees that are paid for transactions
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
   public constructor(
-    url: string,
+    apiUrl: string,
     senderAddress: string,
     signCallback: SigningCallback,
     customFees?: Partial<FeeTable>,
     broadcastMode = BroadcastMode.Block,
   ) {
-    super(url, broadcastMode);
+    super(apiUrl, broadcastMode);
     this.anyValidAddress = senderAddress;
 
     this.senderAddress = senderAddress;

packages/sdk/types/cosmwasmclient.d.ts

@@ -113,7 +113,16 @@ export declare class CosmWasmClient {
   protected anyValidAddress: string | undefined;
   private readonly codesCache;
   private chainId;
-  constructor(url: string, broadcastMode?: BroadcastMode);
+  /**
+   * Creates a new client to interact with a CosmWasm blockchain.
+   *
+   * This instance does a lot of caching. In order to benefit from that you should try to use one instance
+   * for the lifetime of your application. When switching backends, a new instance must be created.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
+  constructor(apiUrl: string, broadcastMode?: BroadcastMode);
   getChainId(): Promise<string>;
   getHeight(): Promise<number>;
   /**

packages/sdk/types/restclient.d.ts

@@ -178,8 +178,19 @@ export declare enum BroadcastMode {
 }
 export declare class RestClient {
   private readonly client;
-  private readonly mode;
-  constructor(url: string, mode?: BroadcastMode);
+  private readonly broadcastMode;
+  /**
+   * Creates a new client to interact with a Cosmos SDK light client daemon.
+   * This class tries to be a direct mapping onto the API. Some basic decoding and normalizatin is done
+   * but things like caching are done at a higher level.
+   *
+   * When building apps, you should not need to use this class directly. If you do, this indicates a missing feature
+   * in higher level components. Feel free to raise an issue in this case.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
+  constructor(apiUrl: string, broadcastMode?: BroadcastMode);
   get(path: string): Promise<RestClientResponse>;
   post(path: string, params: PostTxsParams): Promise<RestClientResponse>;
   authAccounts(address: string): Promise<AuthAccountsResponse>;

packages/sdk/types/signingcosmwasmclient.d.ts

@@ -48,8 +48,20 @@ export declare class SigningCosmWasmClient extends CosmWasmClient {
   readonly senderAddress: string;
   private readonly signCallback;
   private readonly fees;
+  /**
+   * Creates a new client with signing capability to interact with a CosmWasm blockchain. This is the bigger brother of CosmWasmClient.
+   *
+   * This instance does a lot of caching. In order to benefit from that you should try to use one instance
+   * for the lifetime of your application. When switching backends, a new instance must be created.
+   *
+   * @param apiUrl The URL of a Cosmos SDK light client daemon API (sometimes called REST server or REST API)
+   * @param senderAddress The address that will sign and send transactions using this instance
+   * @param signCallback An asynchonous callback to create a signature for a given transaction. This can be implemented using secure key stores that require user interaction.
+   * @param customFees The fees that are paid for transactions
+   * @param broadcastMode Defines at which point of the transaction processing the postTx method (i.e. transaction broadcasting) returns
+   */
   constructor(
-    url: string,
+    apiUrl: string,
     senderAddress: string,
     signCallback: SigningCallback,
     customFees?: Partial<FeeTable>,