Merge pull request #8343 from Agoric/ta/typedoc

generate HTML documentation from TS/JSDoc

.github/workflows/test-all-packages.yml

@@ -72,6 +72,9 @@ jobs:
       # eslint
       - name: yarn lint primary
         run: ./scripts/lint-with-types.sh primary
+      # build the API docs to verify it works
+      - name: build API docs
+        run: yarn docs
 
   lint-rest:
     timeout-minutes: 15

.gitignore

@@ -56,6 +56,7 @@ bundles
 bundle-*.js
 compiled
 dist
+api-docs
 
 # misc
 /.vagrant

docs/typescript.md

@@ -12,3 +12,13 @@ So our best solution is to have one source of truth for the types and auto-gener
 - `src/types.d.ts` is built automatically from types-ambient
   - `prepack` copies types-ambient.js to types.js and appends 'export {};' to turn it into a module, then builds
   - `postpack` deletes the new types.js and .d.ts files
+
+## Generating API docs
+
+We use [TypeDoc](https://typedoc.org/) to render API docs in HTML.
+
+```sh
+yarn docs
+open api-docs/index.html
+```
+

package.json

@@ -33,6 +33,7 @@
     "prettier": "^3.0.3",
     "prettier-plugin-jsdoc": "^1.0.0",
     "type-coverage": "^2.26.3",
+    "typedoc": "^0.25.4",
     "typescript": "~5.2.2"
   },
   "engines": {
@@ -64,6 +65,7 @@
   "scripts": {
     "clean": "yarn lerna run --no-bail clean",
     "check-dependencies": "node ./scripts/check-mismatched-dependencies.cjs",
+    "docs": "typedoc --tsconfig tsconfig.build.json",
     "lerna": "lerna",
     "link-cli": "yarn run create-agoric-cli",
     "create-agoric-cli": "node ./scripts/create-agoric-cli.cjs",
@@ -77,6 +79,7 @@
     "test:xs": "yarn workspaces run test:xs",
     "build": "yarn workspaces run build",
     "postinstall": "patch-package",
+    "build-ts": "tsc --build tsconfig.build.json",
     "build-xs-worker": "cd packages/xs-vat-worker && yarn build:xs-lin"
   },
   "ava": {

packages/ERTP/typedoc.json

@@ -0,0 +1,12 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js"
+    ],
+    "validation": {
+        "notExported": false,
+        "invalidLink": false,
+    }
+}

packages/SwingSet/src/kernel/state/kernelKeeper.js

@@ -553,10 +553,10 @@ export default function makeKernelKeeper(kernelStorage, kernelSlog) {
    * Allocate a new koid.
    *
    * @param {string} ownerID
-   * @param {undefined | bigint} id
+   * @param {bigint} [id]
    * @returns {string}
    */
-  function addKernelObject(ownerID, id = undefined) {
+  function addKernelObject(ownerID, id) {
     // providing id= is only for unit tests
     insistVatID(ownerID);
     if (id === undefined) {

packages/assert/src/types.js

@@ -11,7 +11,7 @@
  * @callback BaseAssert
  * The `assert` function itself.
  *
- * @param {*} flag The truthy/falsy value
+ * @param {any} flag The truthy/falsy value
  * @param {Details} [optDetails] The details to throw
  * @param {ErrorConstructor} [ErrorConstructor] An optional alternate error
  * constructor to use.
@@ -58,8 +58,8 @@
  * The `assert.equal` method
  *
  * Assert that two values must be `Object.is`.
- * @param {*} actual The value we received
- * @param {*} expected What we wanted
+ * @param {any} actual The value we received
+ * @param {any} expected What we wanted
  * @param {Details} [optDetails] The details to throw
  * @param {ErrorConstructor} [ErrorConstructor] An optional alternate error
  * constructor to use.
@@ -193,20 +193,21 @@
  * payload itself is still passed unquoted to the console as it would be
  * without `quote`.
  *
+ * @example
  * For example, the following will reveal the expected sky color, but not the
  * actual incorrect sky color, in the thrown error's message:
  * ```js
  * sky.color === expectedColor || Fail`${sky.color} should be ${quote(expectedColor)}`;
  * ```
- *
+ * @example
  * The normal convention is to locally rename `details` to `X` and `quote` to `q`
  * like `const { details: X, quote: q } = assert;`, so the above example would then be
  * ```js
  * sky.color === expectedColor || Fail`${sky.color} should be ${q(expectedColor)}`;
  * ```
  *
  * @callback AssertQuote
- * @param {*} payload What to declassify
+ * @param {any} payload What to declassify
  * @param {(string|number)} [spaces]
  * @returns {StringablePayload} The declassified payload
  */

packages/assert/typedoc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/assert.js",
+        "src/types.js",
+    ]
+}

packages/boot/tools/supports.ts

@@ -25,7 +25,7 @@ import {
 
 import type { ExecutionContext as AvaT } from 'ava';
 
-import { makeRunUtils } from '@agoric/swingset-vat/tools/run-utils.ts';
+import { makeRunUtils } from '@agoric/swingset-vat/tools/run-utils.js';
 
 const trace = makeTracer('BSTSupport', false);
 

packages/cosmic-swingset/calc-rpcport.js

@@ -11,6 +11,8 @@ import toml from '@iarna/toml';
 
 const configString = fs.readFileSync(process.argv[2]).toString();
 const config = toml.parse(configString);
+// eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+// @ts-ignore Property 'laddr' does not exist on type 'AnyJson'
 const { laddr } = config.rpc; // like tcp://0.0.0.0:26657
 // eslint-disable-next-line no-useless-escape
 const m = laddr.match(/^tcp:\/\/([\d\.]+):(\d+)$/);

packages/governance/src/question.js

@@ -41,6 +41,7 @@ const QuorumRule = /** @type {const} */ ({
 const positionIncluded = (positions, p) => positions.some(e => keyEQ(e, p));
 
 /**
+ * @internal
  * @param {QuestionSpec} allegedQuestionSpec
  * @returns {QuestionSpec}
  */

packages/governance/typedoc.json

@@ -0,0 +1,11 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+        // FIXME hitting errors like: Failed to find JSDoc tag for ParamValueTyped after parsing comment, please file a bug report.
+        // "src/types-ambient.js",
+        "tools/puppetGovernance.js",
+    ]
+}

packages/inter-protocol/typedoc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+        "src/clientSupport.js",
+    ]
+}

packages/internal/src/batched-deliver.js

@@ -3,12 +3,12 @@
 export const DEFAULT_BATCH_TIMEOUT_MS = 1000;
 
 /**
- * @typedef {(message: any[], ackNum: number) => void} DeliverMessages
+ * @typedef {(message: any[], ackNum: number) => Promise<void>} DeliverMessages
  */
 
 /**
  * @param {DeliverMessages} deliver
- * @param {{ clearTimeout: NodeJS.clearTimeout, setTimeout: NodeJS.setTimeout }} io
+ * @param {{ clearTimeout: import('node:timers').clearTimeout, setTimeout: import('node:timers').setTimeout }} io
  * @param {number} batchTimeoutMs
  */
 export function makeBatchedDeliver(
@@ -34,7 +34,7 @@ export function makeBatchedDeliver(
         // Transfer the batched messages to the deliver function.
         const msgs = batchedMessages;
         batchedMessages = [];
-        deliver(msgs, latestAckNum);
+        void deliver(msgs, latestAckNum);
       }, batchTimeoutMs);
     }
 

packages/internal/src/utils.js

@@ -7,7 +7,7 @@ import { isPromise, makePromiseKit } from '@endo/promise-kit';
 import { makeQueue } from '@endo/stream';
 import { asyncGenerate, makeSet } from 'jessie.js';
 
-const { entries, fromEntries, keys, values } = Object;
+const { fromEntries, keys, values } = Object;
 const { ownKeys } = Reflect;
 
 const { details: X, quote: q, Fail } = assert;
@@ -42,51 +42,7 @@ export const fromUniqueEntries = allEntries => {
 };
 harden(fromUniqueEntries);
 
-/**
- * By analogy with how `Array.prototype.map` will map the elements of
- * an array to transformed elements of an array of the same shape,
- * `objectMap` will do likewise for the string-named own enumerable
- * properties of an object.
- *
- * Typical usage applies `objectMap` to a CopyRecord, i.e.,
- * an object for which `passStyleOf(original) === 'copyRecord'`. For these,
- * none of the following edge cases arise. The result will be a CopyRecord
- * with exactly the same property names, whose values are the mapped form of
- * the original's values.
- *
- * When the original is not a CopyRecord, some edge cases to be aware of
- *    * No matter how mutable the original object, the returned object is
- *      hardened.
- *    * Only the string-named enumerable own properties of the original
- *      are mapped. All other properties are ignored.
- *    * If any of the original properties were accessors, `Object.entries`
- *      will cause its `getter` to be called and will use the resulting
- *      value.
- *    * No matter whether the original property was an accessor, writable,
- *      or configurable, all the properties of the returned object will be
- *      non-writable, non-configurable, data properties.
- *    * No matter what the original object may have inherited from, and
- *      no matter whether it was a special kind of object such as an array,
- *      the returned object will always be a plain object inheriting directly
- *      from `Object.prototype` and whose state is only these new mapped
- *      own properties.
- *
- * With these differences, even if the original object was not a CopyRecord,
- * if all the mapped values are Passable, then the returned object will be
- * a CopyRecord.
- *
- * @template {Record<string, any>} O
- * @param {O} original
- * @template R map result
- * @param {(value: O[keyof O], key: keyof O) => R} mapFn
- * @returns {{ [P in keyof O]: R}}
- */
-export const objectMap = (original, mapFn) => {
-  const ents = entries(original);
-  const mapEnts = ents.map(([k, v]) => [k, mapFn(v, k)]);
-  return harden(fromEntries(mapEnts));
-};
-harden(objectMap);
+export { objectMap } from '@endo/patterns';
 
 /**
  * @param {Array<string | symbol>} leftNames

packages/notifier/src/storesub.js

@@ -10,6 +10,7 @@ import { subscribeEach } from './subscribe.js';
 /**
  * NB: does not yet survive upgrade https://github.com/Agoric/agoric-sdk/issues/6893
  *
+ * @alpha
  * @template T
  * @param {Subscriber<T>} subscriber
  * @param {(v: T) => void} consumeValue

packages/notifier/typedoc.json

@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+    ]
+}

packages/store/src/types.js

@@ -132,7 +132,8 @@
 // ///////////////////////// Deprecated Legacy /////////////////////////////////
 
 /**
- * @template K,V
+ * @template K
+ * @template V
  * @typedef {object} LegacyWeakMap LegacyWeakMap is deprecated. Use WeakMapStore
  *   instead if possible.
  * @property {(key: K) => boolean} has Check if a key exists
@@ -145,7 +146,8 @@
  */
 
 /**
- * @template K,V
+ * @template K
+ * @template V
  * @typedef {object} LegacyMap LegacyMap is deprecated. Use MapStore instead if
  *   possible.
  * @property {(key: K) => boolean} has Check if a key exists

packages/store/typedoc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+        "src/types.js"
+    ]
+}

packages/swingset-liveslots/README.md

@@ -0,0 +1,2 @@
+# SwingSet Liveslots
+

packages/swingset-liveslots/src/message.js

@@ -32,7 +32,7 @@ export function insistMessage(message) {
 
 /**
  * @param {unknown} vdo
- * @returns {asserts vdo is VatDeliveryObject}
+ * @returns {asserts vdo is import('./types').VatDeliveryObject}
  */
 
 export function insistVatDeliveryObject(vdo) {
@@ -114,7 +114,7 @@ export function insistVatDeliveryResult(vdr) {
 
 /**
  * @param {unknown} vso
- * @returns {asserts vso is VatSyscallObject}
+ * @returns {asserts vso is import('./types').VatSyscallObject}
  */
 
 export function insistVatSyscallObject(vso) {
@@ -194,7 +194,7 @@ export function insistVatSyscallObject(vso) {
 
 /**
  * @param {unknown} vsr
- * @returns {asserts vsr is VatSyscallResult}
+ * @returns {asserts vsr is import('./types').VatSyscallResult}
  */
 
 export function insistVatSyscallResult(vsr) {

packages/swingset-liveslots/typedoc.json

@@ -0,0 +1,10 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+        "src/types.js",
+        "src/vatDataTypes.js",
+    ]
+}

packages/time/typedoc.json

@@ -0,0 +1,9 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/timeMath.js",
+        "src/types.js"
+    ]
+}

packages/vat-data/src/index.js

@@ -42,10 +42,13 @@ export {
   prepareSingleton,
 } from './exo-utils.js';
 
-/** @typedef {import('@agoric/swingset-liveslots').Baggage} Baggage */
 /** @typedef {import('@agoric/swingset-liveslots').DurableKindHandle} DurableKindHandle */
 /** @template T @typedef {import('@agoric/swingset-liveslots').DefineKindOptions<T>} DefineKindOptions */
 
+// Copy this type because aliasing it by `import('@agoric/swingset-liveslots').Baggage`
+// causes this error in typedoc: Expected a symbol for node with kind Identifier
+/** @typedef {MapStore<string, any>} Baggage */
+
 // //////////////////////////// deprecated /////////////////////////////////////
 
 /**

packages/vat-data/typedoc.json

@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+    ]
+}

packages/vats/src/core/demoIssuers.js

@@ -243,6 +243,7 @@ export const connectFaucet = async ({
   },
   produce: { mints },
 }) => {
+  assert(mints);
   const vats = {
     mints: E(loadVat)('mints'),
   };