Merge pull request #1928 from endojs/ta/more-typedoc

more typedoc
endojs · Jan 8, 2024 · e85d8a7 · e85d8a7
2 parents ecac811 + f0ffdbb
commit e85d8a7
Show file tree

Hide file tree

Showing 15 changed files with 84 additions and 67 deletions.
diff --git a/package.json b/package.json
@@ -23,7 +23,7 @@
     "lerna": "^5.6.2",
     "lerna-update-wizard": "^0.17.5",
     "type-coverage": "^2.26.3",
-    "typedoc": "^0.25.4",
+    "typedoc": "^0.25.7",
     "typescript": "~5.2.2"
   },
   "scripts": {

diff --git a/packages/bundle-source/src/is-entrypoint.js b/packages/bundle-source/src/is-entrypoint.js
@@ -1,7 +1,8 @@
+// @ts-check
 // Detect if this is run as a script.
-import url from 'url';
-import process from 'process';
-import fs from 'fs';
+import * as url from 'url';
+import * as process from 'process';
+import * as fs from 'fs';
 
 // Agoric still uses Endo dependencies under an emulation of ESM we call RESM
 // because it is invoked with `node -r esm`.
@@ -13,4 +14,4 @@ const favor = (primary, secondary) =>
 // FIXME: Should maybe be exported by '@endo/something'?
 export const isEntrypoint = href =>
   String(href) ===
-  url.pathToFileURL(fs.realpathSync(favor(process.argv[1]), '/')).href;
+  url.pathToFileURL(fs.realpathSync(favor(process.argv[1]))).href;
diff --git a/packages/bundle-source/typedoc.json b/packages/bundle-source/typedoc.json
@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "src/index.js",
+    ]
+}
diff --git a/packages/evasive-transform/src/generate.js b/packages/evasive-transform/src/generate.js
@@ -12,7 +12,7 @@ import babelGenerator from '@agoric/babel-generator';
 // OR, upgrading to Babel 8 probably addresses this defect.
 // const { default: generator } = /** @type {any} */ (babelGenerator);
 const generator = /** @type {typeof import('@babel/generator')['default']} */ (
-  // @ts-expect-error
+  // @ts-ignore -- errors but not in typedoc build
   babelGenerator.default || babelGenerator
 );
 

diff --git a/packages/lockdown/typedoc.json b/packages/lockdown/typedoc.json
@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "pre.js",
+    ]
+}
diff --git a/packages/marshal/src/encodeToCapData.js b/packages/marshal/src/encodeToCapData.js
@@ -346,11 +346,6 @@ export const makeDecodeFromCapData = (decodeOptions = {}) => {
           return -Infinity;
         }
         case 'bigint': {
-          // Using @ts-ignore rather than @ts-expect-error below because
-          // with @ts-expect-error I get a red underline in vscode, but
-          // without it I get errors from `yarn lint`.
-          // @ts-ignore inadequate type inference
-          // See https://github.com/endojs/endo/pull/1259#discussion_r954561901
           const { digits } = jsonEncoded;
           typeof digits === 'string' ||
             Fail`invalid digits typeof ${q(typeof digits)}`;
@@ -361,28 +356,13 @@ export const makeDecodeFromCapData = (decodeOptions = {}) => {
           // on environment variable. Eventually remove, but after confident
           // that there are no more supported senders.
           //
-          // Using @ts-ignore rather than @ts-expect-error below because
-          // with @ts-expect-error I get a red underline in vscode, but
-          // without it I get errors from `yarn lint`.
-          // @ts-ignore inadequate type inference
-          // See https://github.com/endojs/endo/pull/1259#discussion_r954561901
           return Symbol.asyncIterator;
         }
         case 'symbol': {
-          // Using @ts-ignore rather than @ts-expect-error below because
-          // with @ts-expect-error I get a red underline in vscode, but
-          // without it I get errors from `yarn lint`.
-          // @ts-ignore inadequate type inference
-          // See https://github.com/endojs/endo/pull/1259#discussion_r954561901
           const { name } = jsonEncoded;
           return passableSymbolForName(name);
         }
         case 'tagged': {
-          // Using @ts-ignore rather than @ts-expect-error below because
-          // with @ts-expect-error I get a red underline in vscode, but
-          // without it I get errors from `yarn lint`.
-          // @ts-ignore inadequate type inference
-          // See https://github.com/endojs/endo/pull/1259#discussion_r954561901
           const { tag, payload } = jsonEncoded;
           return makeTagged(tag, decodeFromCapData(payload));
         }
@@ -411,11 +391,6 @@ export const makeDecodeFromCapData = (decodeOptions = {}) => {
           throw Fail`internal: decodeErrorFromCapData option must return an error: ${decoded}`;
         }
         case 'hilbert': {
-          // Using @ts-ignore rather than @ts-expect-error below because
-          // with @ts-expect-error I get a red underline in vscode, but
-          // without it I get errors from `yarn lint`.
-          // @ts-ignore inadequate type inference
-          // See https://github.com/endojs/endo/pull/1259#discussion_r954561901
           const { original, rest } = jsonEncoded;
           hasOwnPropertyOf(jsonEncoded, 'original') ||
             Fail`Invalid Hilbert Hotel encoding ${jsonEncoded}`;

diff --git a/packages/marshal/src/types.js b/packages/marshal/src/types.js
@@ -4,16 +4,16 @@ export {};
 /**
  * @template Slot
  * @callback ConvertValToSlot
- * @param {import('@endo/pass-style').PassableCap} val
+ * @param {any} val a PassableCap
  * @returns {Slot}
  */
 
 /**
  * @template Slot
  * @callback ConvertSlotToVal
  * @param {Slot} slot
- * @param {import('@endo/pass-style').InterfaceSpec} [iface]
- * @returns {import('@endo/pass-style').PassableCap}
+ * @param {string} [iface]
+ * @returns {any} a PassableCap
  */
 
 /**
@@ -34,7 +34,7 @@ export {};
  *                                      errorId?: string
  *           } |
  *           EncodingClass<'slot'> & { index: number,
- *                                     iface?: import('@endo/pass-style').InterfaceSpec
+ *                                     iface?: string
  *           } |
  *           EncodingClass<'hilbert'> & { original: Encoding,
  *                                        rest?: Encoding
@@ -84,15 +84,15 @@ export {};
 /**
  * @template Slot
  * @callback ToCapData
- * @param {import('@endo/pass-style').Passable} val
+ * @param {any} val a Passable
  * @returns {CapData<Slot>}
  */
 
 /**
  * @template Slot
  * @callback FromCapData
  * @param {CapData<Slot>} data
- * @returns {import('@endo/pass-style').Passable}
+ * @returns {any} a Passable
  */
 
 /**
@@ -172,8 +172,8 @@ export {};
  * ordering would also compare magnitudes, and so agree with the rank ordering
  * of all values other than `NaN`. An array sorted by rank would enable range
  * queries by magnitude.
- * @param {import('@endo/pass-style').Passable} left
- * @param {import('@endo/pass-style').Passable} right
+ * @param {any} left a Passable
+ * @param {any} right a Passable
  * @returns {RankComparison}
  */
 

diff --git a/packages/marshal/test/test-marshal-capdata.js b/packages/marshal/test/test-marshal-capdata.js
@@ -6,6 +6,11 @@ import { makeMarshal } from '../src/marshal.js';
 
 const { freeze, isFrozen, create, prototype: objectPrototype } = Object;
 
+const harden = /** @type {import('ses').Harden & {isFake: boolean}} */ (
+  // eslint-disable-next-line no-undef
+  global.harden
+);
+
 // this only includes the tests that do not use liveSlots
 
 /**
@@ -188,7 +193,6 @@ test('serialize static data', t => {
   const m = makeTestMarshal();
   const ser = val => m.serialize(val);
 
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     t.throws(() => ser([1, 2]), {
       message: /Cannot pass non-frozen objects like/,
@@ -242,22 +246,20 @@ test('serialize errors', t => {
 
   // Extra properties
   const errExtra = Error('has extra properties');
-  // @ts-ignore Check dynamic consequences of type violation
+  // @ts-expect-error Check dynamic consequences of type violation
   errExtra.foo = [];
   freeze(errExtra);
   t.assert(isFrozen(errExtra));
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
-    // @ts-ignore Check dynamic consequences of type violation
+    // @ts-expect-error Check dynamic consequences of type violation
     t.falsy(isFrozen(errExtra.foo));
   }
   t.deepEqual(ser(errExtra), {
     body: '{"@qclass":"error","errorId":"error:anon-marshal#10003","message":"has extra properties","name":"Error"}',
     slots: [],
   });
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
-    // @ts-ignore Check dynamic consequences of type violation
+    // @ts-expect-error Check dynamic consequences of type violation
     t.falsy(isFrozen(errExtra.foo));
   }
 
@@ -332,7 +334,6 @@ test('records', t => {
 
   // empty objects
 
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     // rejected because it is not hardened
     t.throws(

diff --git a/packages/marshal/test/test-marshal-far-function.js b/packages/marshal/test/test-marshal-far-function.js
@@ -5,6 +5,11 @@ import { getInterfaceOf, passStyleOf, Far } from '@endo/pass-style';
 
 const { freeze, setPrototypeOf } = Object;
 
+const harden = /** @type {import('ses').Harden & {isFake: boolean}} */ (
+  // eslint-disable-next-line no-undef
+  global.harden
+);
+
 test('Far functions', t => {
   t.notThrows(() => Far('arrow', a => a + 1), 'Far function');
   const arrow = Far('arrow', a => a + 1);
@@ -21,7 +26,6 @@ test('Acceptable far functions', t => {
 });
 
 test('Unacceptable far functions', t => {
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     t.throws(
       () =>

diff --git a/packages/marshal/test/test-marshal-far-obj.js b/packages/marshal/test/test-marshal-far-obj.js
@@ -12,7 +12,6 @@ const { create, getPrototypeOf, prototype: objectPrototype } = Object;
 
 test('Remotable/getInterfaceOf', t => {
   t.throws(
-    // @ts-ignore We're testing the dynamic consequences of this type violation
     () => Remotable({ bar: 29 }),
     { message: /unimplemented/ },
     'object ifaces are not implemented',
@@ -88,7 +87,7 @@ const testRecord = ({
 
 const goodRemotableProto = testRecord();
 
-// @ts-ignore We're testing bad things anyway
+// @ts-expect-error We're testing bad things anyway
 const badRemotableProto1 = testRecord({ styleSymbol: BAD_PASS_STYLE });
 
 const badRemotableProto2 = testRecord({ styleString: 'string' });
@@ -215,7 +214,7 @@ test('transitional remotables', t => {
         throw Error(`unknown option ${opt}`);
       }
     }
-    // @ts-ignore Don't yet understand typing, but want dynamic test anyway
+    // @ts-expect-error Don't yet understand typing, but want dynamic test anyway
     const o = create(objectPrototype, props);
     if (mark === 'far') {
       return Far('iface', o);

diff --git a/packages/marshal/test/test-marshal-smallcaps.js b/packages/marshal/test/test-marshal-smallcaps.js
@@ -8,6 +8,11 @@ import { roundTripPairs } from './test-marshal-capdata.js';
 
 const { freeze, isFrozen, create, prototype: objectPrototype } = Object;
 
+const harden = /** @type {import('ses').Harden & {isFake: boolean}} */ (
+  // eslint-disable-next-line no-undef
+  global.harden
+);
+
 // this only includes the tests that do not use liveSlots
 
 /**
@@ -34,7 +39,6 @@ test('smallcaps serialize static data', t => {
   const { serialize } = makeTestMarshal();
   const ser = val => serialize(val);
 
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     t.throws(() => ser([1, 2]), {
       message: /Cannot pass non-frozen objects like/,
@@ -102,22 +106,20 @@ test('smallcaps serialize errors', t => {
 
   // Extra properties
   const errExtra = Error('has extra properties');
-  // @ts-ignore Check dynamic consequences of type violation
+  // @ts-expect-error Check dynamic consequences of type violation
   errExtra.foo = [];
   freeze(errExtra);
   t.assert(isFrozen(errExtra));
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
-    // @ts-ignore Check dynamic consequences of type violation
+    // @ts-expect-error Check dynamic consequences of type violation
     t.falsy(isFrozen(errExtra.foo));
   }
   t.deepEqual(ser(errExtra), {
     body: '#{"#error":"has extra properties","name":"Error"}',
     slots: [],
   });
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
-    // @ts-ignore Check dynamic consequences of type violation
+    // @ts-expect-error Check dynamic consequences of type violation
     t.falsy(isFrozen(errExtra.foo));
   }
 
@@ -186,7 +188,6 @@ test('smallcaps records', t => {
 
   // empty objects
 
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     // rejected because it is not hardened
     t.throws(

diff --git a/packages/marshal/test/test-marshal-stringify.js b/packages/marshal/test/test-marshal-stringify.js
@@ -7,6 +7,11 @@ import { roundTripPairs } from './test-marshal-capdata.js';
 
 const { isFrozen } = Object;
 
+const harden = /** @type {import('ses').Harden & {isFake: boolean}} */ (
+  // eslint-disable-next-line no-undef
+  global.harden
+);
+
 test('stringify parse round trip pairs', t => {
   for (const [plain, encoded] of roundTripPairs) {
     const str = stringify(plain);
@@ -27,7 +32,6 @@ test('marshal parse', t => {
 });
 
 test('marshal stringify errors', t => {
-  // @ts-ignore `isFake` purposely omitted from type
   if (!harden.isFake) {
     t.throws(() => stringify([]), {
       message: /Cannot pass non-frozen objects like .*. Use harden()/,

diff --git a/packages/marshal/typedoc.json b/packages/marshal/typedoc.json
@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "index.js"
+    ]
+}
diff --git a/packages/ses/typedoc.json b/packages/ses/typedoc.json
@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.json"
+    ],
+    "entryPoints": [
+        "types.d.ts",
+    ]
+}
diff --git a/yarn.lock b/yarn.lock
@@ -11053,10 +11053,10 @@ shell-quote@^1.6.1:
   resolved "https://registry.yarnpkg.com/shell-quote/-/shell-quote-1.7.3.tgz#aa40edac170445b9a431e17bb62c0b881b9c4123"
   integrity sha512-Vpfqwm4EnqGdlsBFNmHhxhElJYrdfcxPThu+ryKS5J8L/fhAwLazFZtq+S+TWZ9ANj2piSQLGj6NQg+lKPmxrw==
 
-shiki@^0.14.1:
-  version "0.14.5"
-  resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.5.tgz#375dd214e57eccb04f0daf35a32aa615861deb93"
-  integrity sha512-1gCAYOcmCFONmErGTrS1fjzJLA7MGZmKzrBNX7apqSwhyITJg2O102uFzXUeBxNnEkDA9vHIKLyeKq0V083vIw==
+shiki@^0.14.7:
+  version "0.14.7"
+  resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.7.tgz#c3c9e1853e9737845f1d2ef81b31bcfb07056d4e"
+  integrity sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg==
   dependencies:
     ansi-sequence-parser "^1.1.0"
     jsonc-parser "^3.2.0"
@@ -12204,15 +12204,15 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==
 
-typedoc@^0.25.4:
-  version "0.25.4"
-  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.4.tgz#5c2c0677881f504e41985f29d9aef0dbdb6f1e6f"
-  integrity sha512-Du9ImmpBCw54bX275yJrxPVnjdIyJO/84co0/L9mwe0R3G4FSR6rQ09AlXVRvZEGMUg09+z/usc8mgygQ1aidA==
+typedoc@^0.25.7:
+  version "0.25.7"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.7.tgz#11e3f527ca80ca3c029cb8e15f362e6d9f715e25"
+  integrity sha512-m6A6JjQRg39p2ZVRIN3NKXgrN8vzlHhOS+r9ymUYtcUP/TIQPvWSq7YgE5ZjASfv5Vd5BW5xrir6Gm2XNNcOow==
   dependencies:
     lunr "^2.3.9"
     marked "^4.3.0"
     minimatch "^9.0.3"
-    shiki "^0.14.1"
+    shiki "^0.14.7"
 
 "typescript@^3 || ^4":
   version "4.9.5"