Fix documentation rendering

README.md

@@ -7,15 +7,15 @@
 </div>
 
 <p align="center">
-  <a href="https://badge.fury.io/js/stellar-sdk"><img src="https://badge.fury.io/js/stellar-sdk.svg" alt="npm version" height="18"></a>
-  <a href="https://www.npmjs.com/package/stellar-sdk">
-    <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/stellar-sdk" />
+  <a href="https://badge.fury.io/js/@stellar%2Fstellar-sdk"><img src="https://badge.fury.io/js/@stellar%2Fstellar-sdk.svg" alt="npm version" height="18"></a>
+  <a href="https://www.npmjs.com/package/@stellar/stellar-sdk">
+    <img alt="Weekly Downloads" src="https://img.shields.io/npm/dw/@stellar/stellar-sdk" />
   </a>
   <a href="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml"><img alt="Test Status" src="https://github.com/stellar/js-stellar-sdk/actions/workflows/tests.yml/badge.svg" /></a>
 </p>
 
 js-stellar-sdk is a JavaScript library for communicating with a
-[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon) and [Soroban RPC](https://soroban.stellar.org/docs/reference/rpc).
+[Stellar Horizon server](https://github.com/stellar/go/tree/master/services/horizon) and [Soroban RPC](https://developers.stellar.org/network/soroban-rpc).
 It is used for building Stellar apps either on Node.js or in the browser, though it can be used in other environments with some tinkering.
 
 It provides:
@@ -89,14 +89,14 @@ If you don't want to use or install Bower, you can copy the packaged JS files fr
 
 The usage documentation for this library lives in a handful of places:
 
- * across the [Stellar Developer Docs](), which includes tutorials and examples,
+ * across the [Stellar Developer Docs](https://developers.stellar.org), which includes tutorials and examples,
  * within [this repository itself](https://github.com/stellar/js-stellar-sdk/blob/master/docs/reference/readme.md), and
  * on the generated [API doc site](https://stellar.github.io/js-stellar-sdk/).
 
 You can also refer to:
 
  * the [documentation](https://developers.stellar.org/network/horizon) for the Horizon REST API (if using the `Horizon` module) and
- * the [documentation](https://soroban.stellar.org/docs/reference/rpc) for Soroban RPC's API (if using the `rpc` module)
+ * the [documentation](https://developers.stellar.org/network/soroban-rpc) for Soroban RPC's API (if using the `rpc` module)
 
 ### Usage with React-Native
 

config/.jsdoc.json

@@ -3,11 +3,38 @@
     "include": ["lib/", "js-stellar-base/src"],
     "exclude": "js-stellar-base/src/generated"
   },
+  "plugins": ["plugins/markdown"],
+  "template": {
+    "default": {
+      "useLongNameInNav": true
+    }
+  },
   "opts": {
+    "readme": "README.md",
     "destination": "jsdoc/",
     "recurse": true,
-    "template": "node_modules/minami",
-    "readme": "README.md"
+    "verbose": true,
+    "template": "node_modules/clean-jsdoc-theme",
+    "theme_opts": {
+      "default_theme": "fallback-light",
+      "title": "Home",
+      "menu": [
+        {
+          "title": "GitHub",
+          "link": "https://github.com/stellar/js-stellar-sdk",
+          "target": "_blank"
+        },
+        {
+          "title": "npm",
+          "link": "https://www.npmjs.com/package/@stellar/stellar-sdk",
+          "target": "_blank"
+        }
+      ],
+      "prefixModuleToSidebarItems_experimental": true
+    }
   },
-  "plugins": ["plugins/markdown"]
+  "markdown": {
+    "hardwrap": false,
+    "idInHeadings": true
+  }
 }

docs/reference/readme.md

@@ -1,7 +1,7 @@
 ---
 title: Overview
 ---
-The JavaScript Stellar SDK facilitates integration with the Stellar [Horizon API server](https://developers.stellar.org/api/), the Stellar [Soroban RPC server](https://soroban.stellar.org/docs/reference/rpc) and submission of Stellar transactions, either on Node.js or in the browser. It has three main uses: [querying Horizon](#querying-horizon), [interacting with Soroban RPC](), and [building, signing, and submitting transactions to the Stellar network](#building-transactions).
+The JavaScript Stellar SDK facilitates integration with the Stellar [Horizon API server](https://developers.stellar.org/api/), the Stellar [Soroban RPC server](https://developers.stellar.org/network/soroban-rpc) and submission of Stellar transactions, either on Node.js or in the browser. It has three main uses: [querying Horizon](#querying-horizon), [interacting with Soroban RPC](), and [building, signing, and submitting transactions to the Stellar network](#building-transactions).
 
  * [Building and installing the SDK](https://github.com/stellar/js-stellar-sdk)
  * [Examples of using the SDK](./examples.md)

package.json

@@ -47,7 +47,7 @@
     "build:browser": "webpack -c config/webpack.config.browser.js",
     "build:docs": "cross-env NODE_ENV=docs yarn _babel",
     "clean": "rm -rf lib/ dist/ coverage/ .nyc_output/ jsdoc/ test/e2e/.soroban",
-    "docs": "yarn build:docs && jsdoc -c ./config/.jsdoc.json --verbose",
+    "docs": "yarn build:docs && jsdoc -c ./config/.jsdoc.json",
     "test": "yarn build:test && yarn test:node && yarn test:integration && yarn test:browser",
     "test:e2e": "./test/e2e/initialize.sh && ava",
     "test:node": "yarn _nyc mocha --recursive 'test/unit/**/*.js'",
@@ -120,6 +120,7 @@
     "chai": "^4.3.10",
     "chai-as-promised": "^7.1.1",
     "chai-http": "^4.3.0",
+    "clean-jsdoc-theme": "^4.3.0",
     "cross-env": "^7.0.3",
     "dotenv": "^16.4.5",
     "eslint": "^8.57.0",

src/config.ts

@@ -1,15 +1,12 @@
+/**
+ * @typedef {Object} Configuration
+ * @memberof Config
+ * @property {boolean} [allowHttp=false] Allow connecting to http servers, default: `false`. This must be set to false in production deployments!
+ * @property {number} [timeout=0] Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue. You can also use {@link Config} class to set this globally.
+ */
+
 interface Configuration {
-  /**
-   * Allow connecting to http servers, default: `false`. This must be set to false in production deployments!
-   *
-   * @type {boolean}
-   */
   allowHttp: boolean;
-  /**
-   * Allow a timeout, default: 0. Allows user to avoid nasty lag due to TOML resolve issue. You can also use {@link Config} class to set this globally.
-   *
-   * @type {number}
-   */
   timeout: number;
 }
 
@@ -23,18 +20,13 @@ let config = Object.assign({}, defaultConfig);
 /**
  * Global config class.
  *
- * Usage node:
- * ```
+ * @example <caption>Usage in node</caption>
  * import {Config} from 'stellar-sdk';
  * Config.setAllowHttp(true);
  * Config.setTimeout(5000);
- * ```
- *
- * Usage browser:
- * ```
+ * @example <caption>Usage in the browser</caption>
  * StellarSdk.Config.setAllowHttp(true);
  * StellarSdk.Config.setTimeout(5000);
- * ```
  * @static
  */
 class Config {

src/contract/assembled_transaction.ts

@@ -29,6 +29,14 @@ import {
 } from "./utils";
 import { SentTransaction } from "./sent_transaction";
 
+/** @module contract */
+
+/**
+ * An impossible account on the Stellar network
+ * @constant {string}
+ * @default GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF
+ * @memberof module:contract
+ */
 export const NULL_ACCOUNT =
   "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
 
@@ -47,7 +55,7 @@ export const NULL_ACCOUNT =
  * Let's look at examples of how to use `AssembledTransaction` for a variety of
  * use-cases:
  *
- * # 1. Simple read call
+ * #### 1. Simple read call
  *
  * Since these only require simulation, you can get the `result` of the call
  * right after constructing your `AssembledTransaction`:
@@ -80,7 +88,7 @@ export const NULL_ACCOUNT =
  * })
  * ```
  *
- * # 2. Simple write call
+ * #### 2. Simple write call
  *
  * For write calls that will be simulated and then sent to the network without
  * further manipulation, only one more step is needed:
@@ -114,7 +122,7 @@ export const NULL_ACCOUNT =
  * const { result } = await tx.signAndSend()
  * ```
  *
- * # 3. More fine-grained control over transaction construction
+ * #### 3. More fine-grained control over transaction construction
  *
  * If you need more control over the transaction before simulating it, you can
  * set various {@link MethodOptions} when constructing your
@@ -147,7 +155,7 @@ export const NULL_ACCOUNT =
  * If you need to inspect the simulation later, you can access it with
  * `tx.simulation`.
  *
- * # 4. Multi-auth workflows
+ * #### 4. Multi-auth workflows
  *
  * Soroban, and Stellar in general, allows multiple parties to sign a
  * transaction.
@@ -234,6 +242,8 @@ export const NULL_ACCOUNT =
  * To see an even more complicated example, where Alice swaps with Bob but the
  * transaction is invoked by yet another party, check out
  * [test-swap.js](../../test/e2e/src/test-swap.js).
+ *
+ * @memberof module:contract
  */
 export class AssembledTransaction<T> {
   /**

src/contract/basic_node_signer.ts

@@ -1,18 +1,20 @@
 import { Keypair, TransactionBuilder, hash } from "@stellar/stellar-base";
-import type { AssembledTransaction } from "./assembled_transaction";
 import type { Client } from "./client";
 
 /**
- * For use with {@link Client} and {@link AssembledTransaction}.
+ * For use with {@link Client} and {@link module:contract.AssembledTransaction}.
  * Implements `signTransaction` and `signAuthEntry` with signatures expected by
  * those classes. This is useful for testing and maybe some simple Node
  * applications. Feel free to use this as a starting point for your own
  * Wallet/TransactionSigner implementation.
+ *
+ * @memberof module:contract
+ *
+ * @param {Keypair} keypair {@link Keypair} to use to sign the transaction or auth entry
+ * @param {string} networkPassphrase passphrase of network to sign for
  */
 export const basicNodeSigner = (
-  /** {@link Keypair} to use to sign the transaction or auth entry */
   keypair: Keypair,
-  /** passphrase of network to sign for */
   networkPassphrase: string,
 ) => ({
   // eslint-disable-next-line require-await

src/contract/client.ts

@@ -5,19 +5,23 @@ import { AssembledTransaction } from "./assembled_transaction";
 import type { ClientOptions, MethodOptions } from "./types";
 import { processSpecEntryStream } from './utils';
 
+/**
+ * Generate a class from the contract spec that where each contract method
+ * gets included with an identical name.
+ *
+ * Each method returns an {@link AssembledTransaction} that can be used to
+ * modify, simulate, decode results, and possibly sign, & submit the
+ * transaction.
+ *
+ * @memberof module:contract
+ *
+ * @constructor
+ * @param {module:contract.Spec} spec {@link Spec} to construct a Client for
+ * @param {ClientOptions} options see {@link ClientOptions}
+ */
 export class Client {
-  /**
-   * Generate a class from the contract spec that where each contract method
-   * gets included with an identical name.
-   *
-   * Each method returns an {@link AssembledTransaction} that can be used to
-   * modify, simulate, decode results, and possibly sign, & submit the
-   * transaction.
-   */
   constructor(
-    /** {@link Spec} to construct a Client for */
     public readonly spec: Spec,
-    /** see {@link ClientOptions} */
     public readonly options: ClientOptions,
   ) {
     this.spec.funcs().forEach((xdrFn) => {
@@ -53,11 +57,11 @@ export class Client {
   /**
    * Generates a Client instance from the provided ClientOptions and the contract's wasm hash.
    * The wasmHash can be provided in either hex or base64 format.
-   * 
-   * @param wasmHash The hash of the contract's wasm binary, in either hex or base64 format.
-   * @param options The ClientOptions object containing the necessary configuration, including the rpcUrl.
-   * @param format The format of the provided wasmHash, either "hex" or "base64". Defaults to "hex".
-   * @returns A Promise that resolves to a Client instance.
+   *
+   * @param {Buffer | string} wasmHash The hash of the contract's wasm binary, in either hex or base64 format.
+   * @param {ClientOptions} options The ClientOptions object containing the necessary configuration, including the rpcUrl.
+   * @param {('hex' | 'base64')} [format='hex'] The format of the provided wasmHash, either "hex" or "base64". Defaults to "hex".
+   * @returns {Promise<module:contract.Client>} A Promise that resolves to a Client instance.
    * @throws {TypeError} If the provided options object does not contain an rpcUrl.
    */
   static async fromWasmHash(wasmHash: Buffer | string,
@@ -76,10 +80,10 @@ export class Client {
 
   /**
    * Generates a Client instance from the provided ClientOptions and the contract's wasm binary.
-   * 
-   * @param wasm The contract's wasm binary as a Buffer.
-   * @param options The ClientOptions object containing the necessary configuration.
-   * @returns A Promise that resolves to a Client instance.
+   *
+   * @param {Buffer} wasm The contract's wasm binary as a Buffer.
+   * @param {ClientOptions} options The ClientOptions object containing the necessary configuration.
+   * @returns {Promise<module:contract.Client>} A Promise that resolves to a Client instance.
    * @throws {Error} If the contract spec cannot be obtained from the provided wasm binary.
    */
   static async fromWasm(wasm: Buffer, options: ClientOptions): Promise<Client> {
@@ -96,9 +100,9 @@ export class Client {
 
   /**
    * Generates a Client instance from the provided ClientOptions, which must include the contractId and rpcUrl.
-   * 
-   * @param options The ClientOptions object containing the necessary configuration, including the contractId and rpcUrl.
-   * @returns A Promise that resolves to a Client instance.
+   *
+   * @param {ClientOptions} options The ClientOptions object containing the necessary configuration, including the contractId and rpcUrl.
+   * @returns {Promise<module:contract.Client>} A Promise that resolves to a Client instance.
    * @throws {TypeError} If the provided options object does not contain both rpcUrl and contractId.
    */
   static async from(options: ClientOptions): Promise<Client> {

src/contract/rust_result.ts

@@ -52,6 +52,7 @@ export interface ErrorMessage {
  * Part of implementing {@link Result}, a minimal implementation of Rust's
  * `Result` type. Used for contract methods that return Results, to maintain
  * their distinction from methods that simply either return a value or throw.
+ * @private
  */
 export class Ok<T> implements Result<T, never> {
   constructor(readonly value: T) {}
@@ -77,6 +78,7 @@ export class Ok<T> implements Result<T, never> {
  * Part of implementing {@link Result}, a minimal implementation of Rust's
  * `Result` type. Used for contract methods that return Results, to maintain
  * their distinction from methods that simply either return a value or throw.
+ * @private
  */
 export class Err<E extends ErrorMessage> implements Result<never, E> {
   constructor(readonly error: E) {}

src/contract/sent_transaction.ts

@@ -20,6 +20,12 @@ import type { AssembledTransaction } from "./assembled_transaction";
  *    {@link MethodOptions.timeoutInSeconds} seconds. See all attempts in
  *    `getTransactionResponseAll` and the most recent attempt in
  *    `getTransactionResponse`.
+ *
+ * @memberof module:contract
+ * @constructor
+ *
+ * @param {function} signTransaction More info in {@link MethodOptions}
+ * @param {module:contract.AssembledTransaction<T>} assembled {@link AssembledTransaction} from which this SentTransaction was initialized
  */
 export class SentTransaction<T> {
   public server: Server;
@@ -61,6 +67,10 @@ export class SentTransaction<T> {
         "You must provide a `signTransaction` function to send a transaction",
       );
     }
+    /**
+     * An RPC server that will be used to send this transaction to the network.
+     * @type {module:rpc.Server}
+     */
     this.server = new Server(this.assembled.options.rpcUrl, {
       allowHttp: this.assembled.options.allowHttp ?? false,
     });
@@ -72,9 +82,7 @@ export class SentTransaction<T> {
    * network.
    */
   static init = async <U>(
-    /** More info in {@link MethodOptions} */
     signTransaction: ClientOptions["signTransaction"],
-    /** {@link AssembledTransaction} from which this SentTransaction was initialized */
     assembled: AssembledTransaction<U>,
   ): Promise<SentTransaction<U>> => {
     const tx = new SentTransaction(signTransaction, assembled);
@@ -103,6 +111,10 @@ export class SentTransaction<T> {
       },
     );
 
+    /**
+     * The transaction, signed by the necessary keypair(s), ready for submission to the network.
+     * @type {Types.Tx}
+     */
     this.signed = TransactionBuilder.fromXDR(
       signature,
       this.assembled.options.networkPassphrase,