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://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-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/docs/data/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:
@@ -96,14 +96,14 @@ USE_AXIOS=false npm run build:browser
 
 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/docs/data/horizon) for the Horizon REST API (if using the `Horizon` module) and
+ * the [documentation](https://developers.stellar.org/docs/data/rpc) for Soroban RPC's API (if using the `rpc` module)
 
 ### Usage with React-Native
 

config/.jsdoc.json

@@ -1,13 +1,51 @@
 {
+  "tags": {
+    "allowUnknownTags": ["optional", "category", "warning", "note", "link"]
+  },
+  "plugins": [
+    "plugins/markdown",
+    "node_modules/better-docs/typescript",
+    "node_modules/better-docs/category"
+  ],
   "source": {
     "include": ["lib/", "js-stellar-base/src"],
+    "includePattern": "\\.(js|ts)$",
     "exclude": "js-stellar-base/src/generated"
   },
   "opts": {
+    "encoding": "utf8",
+    "readme": "README.md",
     "destination": "jsdoc/",
     "recurse": true,
-    "template": "node_modules/minami",
-    "readme": "README.md"
+    "verbose": true,
+    "template": "node_modules/better-docs",
+    "private": true
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "search": true,
+    "default": {
+      "useLongnameInNav": true
+    },
+    "better-docs": {
+      "name": "@stellar/stellar-sdk",
+      "title": "@stellar/stellar-sdk Documentation",
+      "hideGenerator": false,
+      "navLinks": [
+        {
+          "label": "GitHub",
+          "href": "https://github.com/stellar/js-stellar-sdk"
+        },
+        {
+          "label": "npm",
+          "href": "https://www.npmjs.com/package/@stellar/stellar-sdk"
+        }
+      ]
+    }
   },
-  "plugins": ["plugins/markdown"]
+  "markdown": {
+    "hardwrap": false,
+    "idInHeadings": true
+  }
 }

config/.prettierignore

@@ -2,4 +2,5 @@
 ../node_modules
 ../lib
 ../dist
-../docs
+../docs
+../test/unit/out/contract_spec.js

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

@@ -95,7 +95,7 @@
     "build:browser:all": "yarn build:browser && cross-env no_clean=true yarn build:browser:no-axios && cross-env no_clean=true yarn build:browser:no-eventsource && cross-env no_clean=true yarn build:browser:minimal",
     "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 && yarn _nyc mocha --recursive 'test/e2e/src/test-*.js'",
     "test:node": "yarn _nyc mocha --recursive 'test/unit/**/*.js'",
@@ -166,6 +166,7 @@
     "babel-loader": "^9.1.3",
     "babel-plugin-istanbul": "^7.0.0",
     "babel-plugin-transform-define": "^2.1.4",
+    "better-docs": "^2.7.3",
     "buffer": "^6.0.3",
     "chai": "^4.3.10",
     "chai-as-promised": "^7.1.1",
@@ -196,7 +197,6 @@
     "karma-webpack": "^5.0.1",
     "lint-staged": "^15.2.10",
     "lodash": "^4.17.21",
-    "minami": "^1.1.1",
     "mocha": "^10.6.0",
     "node-polyfill-webpack-plugin": "^3.0.0",
     "null-loader": "^4.0.1",

src/config.ts

@@ -1,14 +1,15 @@
-interface Configuration {
+/**
+ * Global config parameters.
+ */
+export interface Configuration {
   /**
-   * Allow connecting to http servers, default: `false`. This must be set to false in production deployments!
-   *
-   * @type {boolean}
+   * Allow connecting to http servers. This must be set to false in production deployments!
+   * @default false
    */
   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}
+   * Allow a timeout. Allows user to avoid nasty lag due network issues.
+   * @default 0
    */
   timeout: number;
 }
@@ -23,54 +24,52 @@ let config = { ...defaultConfig};
 /**
  * Global config class.
  *
- * Usage node:
- * ```
- * import {Config} from 'stellar-sdk';
+ * @hideconstructor
+ *
+ * @example <caption>Usage in node</caption>
+ * import { Config } from '@stellar/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 {
   /**
-   * Sets `allowHttp` flag globally. When set to `true`, connections to insecure http protocol servers will be allowed.
-   * Must be set to `false` in production. Default: `false`.
-   * @param {boolean} value new allowHttp value
-   * @returns {void}
+   * Sets `allowHttp` flag globally. When set to `true`, connections to insecure
+   * http protocol servers will be allowed. Must be set to `false` in
+   * production.
+   * @default false
    * @static
    */
   public static setAllowHttp(value: boolean): void {
     config.allowHttp = value;
   }
 
   /**
-   * Sets `timeout` flag globally. When set to anything besides 0, the request will timeout after specified time (ms).
-   * Default: 0.
-   * @param {number} value new timeout value
-   * @returns {void}
+   * Sets `timeout` flag globally. When set to anything besides 0, the request
+   * will timeout after specified time (ms).
+   * @default 0
    * @static
    */
   public static setTimeout(value: number): void {
     config.timeout = value;
   }
 
   /**
+   * Returns the configured `allowHttp` flag.
    * @static
-   * @returns {boolean} allowHttp flag
+   * @returns {boolean}
    */
   public static isAllowHttp(): boolean {
     return config.allowHttp;
   }
 
   /**
+   * Returns the configured `timeout` flag.
    * @static
-   * @returns {number} timeout flag
+   * @returns {number}
    */
   public static getTimeout(): number {
     return config.timeout;
@@ -79,7 +78,6 @@ class Config {
   /**
    * Sets all global config flags to default values.
    * @static
-   * @returns {void}
    */
   public static setDefault(): void {
     config = { ...defaultConfig};

src/contract/assembled_transaction.ts

@@ -18,7 +18,7 @@ import type {
   Tx,
   XDR_BASE64,
 } from "./types";
-import { Server } from "../rpc/server";
+import { Server } from "../rpc";
 import { Api } from "../rpc/api";
 import { assembleTransaction } from "../rpc/transaction";
 import type { Client } from "./client";
@@ -32,6 +32,8 @@ import { DEFAULT_TIMEOUT } from "./types";
 import { SentTransaction } from "./sent_transaction";
 import { Spec } from "./spec";
 
+/** @module contract */
+
 /**
  * The main workhorse of {@link Client}. This class is used to wrap a
  * transaction-under-construction and provide high-level interfaces to the most
@@ -47,7 +49,7 @@ import { Spec } from "./spec";
  * 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 +82,7 @@ import { Spec } from "./spec";
  * })
  * ```
  *
- * # 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 +116,7 @@ import { Spec } from "./spec";
  * 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 +149,7 @@ import { Spec } from "./spec";
  * 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 +236,8 @@ import { Spec } from "./spec";
  * 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> {
   /**
@@ -401,7 +405,7 @@ export class AssembledTransaction<T> {
     }
     const method = invokeContractArgs.functionName().toString('utf-8');
     const txn = new AssembledTransaction(
-      { ...options, 
+      { ...options,
         method,
         parseResultXdr: (result: xdr.ScVal) =>
           spec.funcResToNative(method, result),
@@ -431,10 +435,11 @@ export class AssembledTransaction<T> {
    * If you don't want to simulate the transaction, you can set `simulate` to
    * `false` in the options.
    *
-   *     const tx = await AssembledTransaction.build({
-   *       ...,
-   *       simulate: false,
-   *     })
+   * @example
+   * const tx = await AssembledTransaction.build({
+   *   ...,
+   *   simulate: false,
+   * })
    */
   static async build<T>(
     options: AssembledTransactionOptions<T>,
@@ -557,7 +562,7 @@ export class AssembledTransaction<T> {
     if (Api.isSimulationRestore(simulation)) {
       throw new AssembledTransaction.Errors.ExpiredState(
         `You need to restore some contract state before you can invoke this method.\n` +
-        'You can set `restore` to true in the method options in order to ' + 
+        'You can set `restore` to true in the method options in order to ' +
         'automatically restore the contract state when needed.'
       );
     }
@@ -597,7 +602,7 @@ export class AssembledTransaction<T> {
   }
 
   /**
-   * Sign the transaction with the signTransaction function included previously. 
+   * Sign the transaction with the signTransaction function included previously.
    * If you did not previously include one, you need to include one now.
    */
   sign = async ({
@@ -674,9 +679,9 @@ export class AssembledTransaction<T> {
   }
 
   /**
-   * Sign the transaction with the `signTransaction` function included previously. 
-   * If you did not previously include one, you need to include one now. 
-   * After signing, this method will send the transaction to the network and 
+   * Sign the transaction with the `signTransaction` function included previously.
+   * If you did not previously include one, you need to include one now.
+   * After signing, this method will send the transaction to the network and
    * return a `SentTransaction` that keeps track * of all the attempts to fetch the transaction.
    */
   signAndSend = async ({
@@ -875,28 +880,28 @@ export class AssembledTransaction<T> {
   }
 
   /**
-   * Restores the footprint (resource ledger entries that can be read or written) 
-   * of an expired transaction. 
-   * 
+   * Restores the footprint (resource ledger entries that can be read or written)
+   * of an expired transaction.
+   *
    * The method will:
    * 1. Build a new transaction aimed at restoring the necessary resources.
    * 2. Sign this new transaction if a `signTransaction` handler is provided.
    * 3. Send the signed transaction to the network.
    * 4. Await and return the response from the network.
-   * 
+   *
    * Preconditions:
    * - A `signTransaction` function must be provided during the Client initialization.
    * - The provided `restorePreamble` should include a minimum resource fee and valid
    *   transaction data.
-   * 
-   * @throws {Error} - Throws an error if no `signTransaction` function is provided during 
+   *
+   * @throws {Error} - Throws an error if no `signTransaction` function is provided during
    * Client initialization.
-   * @throws {AssembledTransaction.Errors.RestoreFailure} - Throws a custom error if the 
+   * @throws {AssembledTransaction.Errors.RestoreFailure} - Throws a custom error if the
    * restore transaction fails, providing the details of the failure.
    */
   async restoreFootprint(
     /**
-     * The preamble object containing data required to 
+     * The preamble object containing data required to
      * build the restore transaction.
      */
     restorePreamble: {