feat: implement typedoc in vitepress (#1115)

* feat: implement typedoc in docs

* feat: add typedoc to address and interfaces

* feat: generate typedoc docs

* feat: implment typedoc in vitepress

* feat: add api docs readme

* chore: linting

* chore: changeset

* chore: update docs git ignore to exclude built docs

* chore: remove api docs files

* chore: update typedoc config

* docs: update interface typedoc

* feat: include typedoc in vitepress dev script

* feat: reslove tsdoc linting warnings

---------

Co-authored-by: danielbate <--global>

.changeset/pink-pens-turn.md

@@ -0,0 +1,2 @@
+---
+---

apps/docs/.gitignore

@@ -1,2 +1,4 @@
 .vitepress/cache
 .vitepress/.temp
+
+src/api

apps/docs/.typedoc/api-readme.md

@@ -0,0 +1,10 @@
+<script setup>
+  import { data } from '../versions.data'
+  const { forc, fuels, fuelCore } = data
+</script>
+
+# The Fuel TypeScript SDK API Documentation
+
+<br/>
+
+#### Version Notice: Docs generated using Fuels `v{{fuels}}`, Fuel Core `v{{fuelCore}}`, Sway `v{{forc}}`, and Forc `v{{forc}}`.

apps/docs/.vitepress/config.ts

@@ -354,6 +354,42 @@ export default defineConfig({
           },
         ],
       },
+      {
+        text: 'API',
+        link: '/api/',
+        items: [
+          {
+            text: 'Address',
+            link: '/api/modules/fuel_ts_address',
+            collapsed: true,
+            items: [
+              {
+                text: 'Address',
+                link: '/api/classes/fuel_ts_address-Address',
+              },
+            ],
+          },
+          {
+            text: 'Interfaces',
+            link: '/api/modules/fuel_ts_interfaces',
+            collapsed: true,
+            items: [
+              {
+                text: 'AbstractAccount',
+                link: 'api/classes/fuel_ts_interfaces-AbstractAccount',
+              },
+              {
+                text: 'AbstractAddress',
+                link: 'api/classes/fuel_ts_interfaces-AbstractAddress',
+              },
+              {
+                text: 'AbstractContract',
+                link: 'api/classes/fuel_ts_interfaces-AbstractContract',
+              },
+            ],
+          },
+        ],
+      },
     ],
   },
 });

apps/docs/package.json

@@ -4,22 +4,26 @@
   "version": "0.41.1",
   "description": "",
   "scripts": {
-    "dev": "nodemon --config nodemon.config.json -x 'vitepress dev'",
-    "build": "vitepress build",
-    "preview": "vitepress preview"
+    "dev": "nodemon --config nodemon.config.json -x 'typedoc && vitepress dev'",
+    "build": "typedoc && vitepress build",
+    "preview": "typedoc && vitepress preview",
+    "docs": "typedoc"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@fuel-ts/versions": "workspace:*"
+    "@fuel-ts/versions": "workspace:*",
+    "typedoc-plugin-markdown": "^3.15.3"
   },
   "devDependencies": {
     "@types/markdown-it": "^12.2.3",
     "@vue/devtools-api": "^6.5.0",
     "flexsearch": "^0.7.31",
     "markdown-it": "^13.0.1",
     "nodemon": "^2.0.22",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-merge-modules": "^5.0.1",
     "vitepress": "1.0.0-alpha.51",
     "vitepress-plugin-search": "1.0.4-alpha.19",
     "vue": "^3.2.47"

apps/docs/typedoc.json

@@ -0,0 +1,27 @@
+{
+  // ************** //
+  // TypeDoc Config
+  // ************** //
+  "$schema": "https://typedoc.org/schema.json",
+  "includeVersion": true,
+  "entryPointStrategy": "packages",
+  "entryPoints": ["../../packages/address", "../../packages/interfaces"],
+  "out": "src/api",
+  "githubPages": false,
+  "readme": ".typedoc/api-readme.md",
+  "categorizeByGroup": true,
+  "cacheBust": true,
+  "hideGenerator": true,
+  "plugin": ["typedoc-plugin-markdown", "typedoc-plugin-merge-modules"],
+  "filenameSeparator": "-",
+  // ********************** //
+  // Markdown Config
+  // ********************** //
+  "hideBreadcrumbs": true,
+  "hideInPageTOC": true,
+  "entryDocument": "index.md",
+  // ******************** //
+  // Merge Modules Config
+  // ******************** //
+  "mergeModulesMergeMode": "module"
+}

packages/address/src/address.ts

@@ -18,11 +18,18 @@ import {
 
 const logger = new Logger(versions.FUELS);
 
+/**
+ * `Address` provides a type safe wrapper for converting between different address formats
+ * ands comparing them for equality.
+ */
 export default class Address extends AbstractAddress {
   // #region address-2
   readonly bech32Address: Bech32Address;
   // #endregion address-2
 
+  /**
+   * @param address - A Bech32 address
+   */
   constructor(address: Bech32Address) {
     super();
     logger.checkNew(new.target, Address);
@@ -34,52 +41,63 @@ export default class Address extends AbstractAddress {
   }
 
   /**
-   * @returns This address as a Bech32m string
+   * Returns the `bech32Address` property
+   *
+   * @returns The `bech32Address` property
    */
   toAddress(): Bech32Address {
     return this.bech32Address;
   }
 
   /**
-   * @returns This address as 256 bit hash string
+   * Converts and returns the `bech32Address` property to a 256 bit hash string
+   *
+   * @returns The `bech32Address` property as a 256 bit hash string
    */
   toB256(): B256Address {
     return toB256(this.bech32Address);
   }
 
   /**
-   * @returns Returns this address as a byte array
+   * Converts and returns the `bech32Address` property to a byte array
+   *
+   * @returns The `bech32Address` property as a byte array
    */
   toBytes(): Uint8Array {
     return getBytesFromBech32(this.bech32Address);
   }
 
   /**
-   * @returns This address as hexed 256 bit hash string
+   * Converts
+   *
+   * @returns The `bech32Address` property as a 256 bit hash string
    */
   toHexString(): B256Address {
     return this.toB256();
   }
 
   /**
-   * Prints this Address value
-   * @returns a string address in Bech32m Format
+   * Converts and returns the `bech32Address` property as a string
+   *
+   * @returns The `bech32Address` property as a string
    */
   toString(): string {
     return this.bech32Address;
   }
 
   /**
-   * Parses this Address value
-   * @returns a string address in Bech32m Format
+   * Converts and returns the `bech32Address` property as a string
+   *
+   * @returns The `bech32Address` property as a string
    */
   toJSON(): string {
-    return this.toString();
+    return this.bech32Address;
   }
 
   /**
-   * Returns the address value as an EvmAddress
-   * @returns the bech32 address as an EvmAddress
+   * Clears the first 12 bytes of the `bech32Address` property and returns it as a `EvmAddress`
+   *
+   * @returns The `bech32Address` property as an {@link EvmAddress | `EvmAddress`}
    */
   toEvmAddress(): EvmAddress {
     const b256Address = toB256(this.bech32Address);
@@ -90,72 +108,79 @@ export default class Address extends AbstractAddress {
   }
 
   /**
-   * Returns the value of this Address value
-   * @returns a string address in Bech32m Format
+   * Returns the value of the `bech32Address` property
+   *
+   * @returns The value of `bech32Address` property
    */
   valueOf(): string {
-    return this.toString();
+    return this.bech32Address;
   }
 
   /**
-   * Compare this Address value to another for direct equality
-   * @param other - the other address to compare against
-   * @returns true if addresses are equal
+   * Compares this the `bech32Address` property to another for direct equality
+   *
+   * @param other - Another address to compare against
+   * @returns The equality of the comparison
    */
   equals(other: Address): boolean {
     return this.bech32Address === other.bech32Address;
   }
 
   /**
-   * Takes a Public Key, hashes it, and creates an Address
-   * @param publicKey - the wallets public key
-   * @returns a new `Address` instance
+   * Takes a Public Key, hashes it, and creates an `Address`
+   *
+   * @param publicKey - A wallets public key
+   * @returns A new `Address` instance
    */
   static fromPublicKey(publicKey: string): Address {
     const b256Address = sha256(publicKey);
     return new Address(toBech32(b256Address));
   }
 
   /**
-   * Takes a B256Address and creates an Address
-   * @param b256Address - the b256 hash
-   * @returns a new `Address` instance
+   * Takes a B256 Address and creates an `Address`
+   *
+   * @param b256Address - A b256 hash
+   * @returns A new `Address` instance
    */
   static fromB256(b256Address: string): Address {
     return new Address(toBech32(b256Address));
   }
 
   /**
-   * Creates a random address within an Address
-   * @returns a new `Address` instance
+   * Creates an `Address` with a randomized `bech32Address` property
+   *
+   * @returns A new `Address` instance
    */
   static fromRandom(): Address {
     return this.fromB256(getRandomB256());
   }
 
   /**
-   * Takes an ambiguous string and attempts to create an Address
-   * @returns a new `Address` instance
+   * Takes an ambiguous string and attempts to create an `Address`
+   *
+   * @param address - An ambiguous string
+   * @returns A new `Address` instance
    */
   static fromString(address: string): Address {
     return isBech32(address) ? new Address(address as Bech32Address) : this.fromB256(address);
   }
 
   /**
-   * Takes an ambiguous string or address and creates an address
+   * Takes an ambiguous string or address and creates an `Address`
+   *
    * @returns a new `Address` instance
    */
   static fromAddressOrString(address: string | AbstractAddress): AbstractAddress {
     return typeof address === 'string' ? this.fromString(address) : address;
   }
 
   /**
-   * Takes an optional string and returns back an Address
+   * Takes a dynamic string or `AbstractAddress` and creates an `Address`
    *
-   * @param addressId - Can be a string containing Bech32, B256, or Public Key
-   * @throws Error
-   * thrown if the input string is not nilsy and cannot be resolved to a valid address format
-   * @returns a new `Address` instance
+   * @param addressId - A string containing Bech32, B256, or Public Key
+   * @throws Error - Unknown address if the format is not recognised
+   * @returns A new `Address` instance
    */
   static fromDynamicInput(address: string | AbstractAddress): Address {
     // If address is a object than we assume it's a AbstractAddress
@@ -180,8 +205,9 @@ export default class Address extends AbstractAddress {
   }
 
   /**
-   * Takes an EvmAddress and returns back an Address
-   * @returns a new `Address` instance
+   * Takes an `EvmAddress` and returns back an `Address`
+   *
+   * @returns A new `Address` instance
    */
   static fromEvmAddress(evmAddress: EvmAddress): Address {
     return new Address(toBech32(evmAddress.value));