Absolutely BASED documentation rendering fixes (#965)

* update README badges * remove conflicting class tags from call builder classesmd * make WebAuth show up as a namespace * collect methods and classes into a SorobanRpc namespace for JSDoc * create a Horizon JSDoc namespace and add the server class to it * Fix all broken links to API dev docs * add the Durability enum to the SorobanRPC JSDoc namespace * create a util namespace and add validateTimebounds to it * remove unnecessary code blocks from ContractSpec examples * group some const declarations into more relevant namespaces/classes * make a stellartoml JSDoc namespace * make federation a module, include the typedefs * mark most of the "call builder" classes as private in JSDoc Since the comments clearly say "don't make this class yourself," it might make sense to mark them as `@private` so they don't show up in the documentation. The doc pages for those classes can still be visited, but they don't show up in the sidebar to the left, unless you specifically navigate to one of them. (Or, if you click a link for what the return type on the `Horizon.Server.effects()` method, for example * mark the Ok and Err rust type classes as private in JSDoc I don't _think_ they're accessible by SDK users, so I think it makes sense to not render them in the docs? * change StellarToml from a JSDoc namespace to a module * change webauth from a JSDoc namespace to a module * mark the AccountResponse class as private in JSDoc * add soroban tx timeout const to the SorobanRpc.Server module * try out a new JSDoc theme * make contract a JSDoc module There was a weird `_default` global that came up from this. Not sure why, but this seems to have done the trick without anything weird going on after. * mark contract/utils functions as private in JSDoc * break the errors classes into multiple files for JSDoc rendering * add JSDoc type definition to friendbot api because more type definitions are more better, right? * add default value to max toml file size in JSDoc * clarify note about when the timebounds are added to client txs
stellar · Sep 24, 2024 · afb7814 · afb7814
1 parent 4aba86f
commit afb7814
Show file tree

Hide file tree

Showing 58 changed files with 1,771 additions and 792 deletions.
diff --git a/README.md b/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
 

diff --git a/config/.jsdoc.json b/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
+  }
 }
diff --git a/config/.prettierignore b/config/.prettierignore
@@ -2,4 +2,5 @@
 ../node_modules
 ../lib
 ../dist
-../docs
+../docs
+../test/unit/out/contract_spec.js
diff --git a/docs/reference/readme.md b/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)

diff --git a/package.json b/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",

diff --git a/src/config.ts b/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};

diff --git a/src/contract/assembled_transaction.ts b/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: {