chore: Fix more lint warnings (#9690)

Ref #9632 ## Description * Fix bad JSDoc `@import`s * Make eslint-plugin-jsdoc aware of TypeDoc tags ### Security Considerations None; this PR only affects JSDoc comments. ### Scaling Considerations n/a ### Documentation Considerations Existing TypeDoc annotations are preserved and explicit support for currently-unused ones is added. ### Testing Considerations This should resolve all `Bad @import tag` and `Invalid JSDoc tag name` linter complaints. It currently upgrades [rule `check-tag-names`](https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-tag-names.md) violations to level "error" since we should not be using any unknown tags, but that could be relaxed if we find such configuration to be overly strict. ### Upgrade Considerations None.
Agoric · Jul 12, 2024 · cc6a9e5 · cc6a9e5
2 parents 7b85450 + 02ff11e
commit cc6a9e5
Show file tree

Hide file tree

Showing 11 changed files with 46 additions and 28 deletions.
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -114,6 +114,27 @@ module.exports = {
     // The default is 'warn', but we want to enforce 'error'.
     '@jessie.js/safe-await-separator': 'error',
 
+    'jsdoc/check-tag-names': [
+      'error',
+      {
+        // TypeDoc adds tags not otherwise known to JSDoc
+        // https://typedoc.org/guides/tags/
+        definedTags: [
+          'alpha',
+          'beta',
+          'category',
+          'categoryDescription',
+          'defaultValue',
+          'document',
+          'group',
+          'groupDescription',
+          'internal',
+          'privateRemarks',
+          'remarks',
+        ],
+      },
+    ],
+
     // CI has a separate format check but keep this warn to maintain that "eslint --fix" prettifies
     // UNTIL https://github.com/Agoric/agoric-sdk/issues/4339
     'prettier/prettier': 'warn',

diff --git a/packages/ERTP/src/legacy-payment-helpers.js b/packages/ERTP/src/legacy-payment-helpers.js
@@ -6,8 +6,8 @@ import { mustMatch } from '@agoric/store';
 import { AmountMath } from './amountMath.js';
 
 /**
- * @import {ERef} from '@endo/far');
- * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js'
+ * @import {ERef} from '@endo/far';
+ * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.js';
  */
 
 /**

diff --git a/packages/ERTP/src/transientNotifier.js b/packages/ERTP/src/transientNotifier.js
@@ -6,7 +6,7 @@ import { makeNotifierKit } from '@agoric/notifier';
 
 /**
  * @import {Purse} from './types.js';
- * @import {LatestTopic, NotifierRecord} from '@agoric/notifier');
+ * @import {LatestTopic, NotifierRecord} from '@agoric/notifier';
  */
 
 // Note: Virtual for high cardinality, but *not* durable, and so

diff --git a/packages/ERTP/src/types.js b/packages/ERTP/src/types.js
@@ -5,9 +5,9 @@ export {};
 
 /// <reference types="ses" />
 /**
- * @import {Passable, RemotableObject} from '@endo/pass-style')
- * @import {CopyBag, CopySet, Key} from '@endo/patterns')
- * @import {LatestTopic, NotifierRecord} from '@agoric/notifier');
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {CopyBag, CopySet, Key} from '@endo/patterns';
+ * @import {LatestTopic, NotifierRecord} from '@agoric/notifier';
  */
 
 /** @typedef {{ brand: Brand<'nat'>; value: bigint }} NatAmount */

diff --git a/packages/SwingSet/src/types-external.js b/packages/SwingSet/src/types-external.js
@@ -1,10 +1,10 @@
-/** @import { ERef } from '@endo/far' */
+/** @import { ERef } from '@endo/far'; */
 
 export {};
 
 /**
- * @import {Guarded} from '@endo/exo')
- * @import {Passable, RemotableObject} from '@endo/pass-style')
+ * @import {Guarded} from '@endo/exo';
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
  */
 
 /* This file defines types that part of the external API of swingset. That

diff --git a/packages/SwingSet/src/vats/timer/vat-timer.js b/packages/SwingSet/src/vats/timer/vat-timer.js
@@ -16,21 +16,21 @@ import { makeScalarWeakMapStore } from '@agoric/store';
 import { TimeMath } from '@agoric/time';
 
 /**
- * @import {Passable, RemotableObject} from '@endo/pass-style')
- * @import {Key} from '@endo/patterns')
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {Key} from '@endo/patterns';
  */
 
 // This consumes O(N) RAM only for outstanding promises, via wakeAt(),
 // delay(), and Notifiers/Iterators (for each actively-waiting
 // client). Everything else should remain in the DB.
 
 /**
- * @import {Timestamp} from '@agoric/time'
- * @import {TimestampRecord} from '@agoric/time'
- * @import {TimestampValue} from '@agoric/time'
- * @import {RelativeTime} from '@agoric/time'
- * @import {RelativeTimeValue} from '@agoric/time'
- * @import {TimerService} from '@agoric/time'
+ * @import {Timestamp} from '@agoric/time';
+ * @import {TimestampRecord} from '@agoric/time';
+ * @import {TimestampValue} from '@agoric/time';
+ * @import {RelativeTime} from '@agoric/time';
+ * @import {RelativeTimeValue} from '@agoric/time';
+ * @import {TimerService} from '@agoric/time';
  *
  * @typedef {object} Handler
  * Handler is a user-provided Far object with .wake(time) used for callbacks

diff --git a/packages/inter-protocol/src/proposals/utils.js b/packages/inter-protocol/src/proposals/utils.js
@@ -3,7 +3,7 @@ import { E } from '@endo/far';
 import { WalletName } from '@agoric/internal';
 import { getCopyMapEntries, makeCopyMap } from '@agoric/store';
 
-/** @import {CopyMap} from '@endo/patterns') */
+/** @import {CopyMap} from '@endo/patterns'; */
 
 /**
  * @param {ERef<import('@agoric/vats').NameAdmin>} nameAdmin

diff --git a/packages/store/src/stores/scalarMapStore.js b/packages/store/src/stores/scalarMapStore.js
@@ -17,8 +17,8 @@ import { makeWeakMapStoreMethods } from './scalarWeakMapStore.js';
 import { makeCurrentKeysKit } from './store-utils.js';
 
 /**
- * @import {Passable} from '@endo/pass-style');
- * @import {Key, Pattern} from '@endo/patterns');
+ * @import {Passable} from '@endo/pass-style';
+ * @import {Key, Pattern} from '@endo/patterns';
  * @import {MapStore, MapStoreMethods, StoreOptions} from '../types.js';
  */
 

diff --git a/packages/store/src/stores/scalarSetStore.js b/packages/store/src/stores/scalarSetStore.js
@@ -12,7 +12,7 @@ import { makeWeakSetStoreMethods } from './scalarWeakSetStore.js';
 import { makeCurrentKeysKit } from './store-utils.js';
 
 /**
- * @import {Key, Pattern} from '@endo/patterns');
+ * @import {Key, Pattern} from '@endo/patterns';
  * @import {SetStore, SetStoreMethods, StoreOptions} from '../types.js';
  */
 

diff --git a/packages/vats/src/lib-board.js b/packages/vats/src/lib-board.js
@@ -17,7 +17,7 @@ import { crc6 } from './crc.js';
 
 /**
  * @import {RemotableObject} from '@endo/pass-style';
- * @import {Key} from '@endo/patterns');
+ * @import {Key} from '@endo/patterns';
  */
 
 export const DEFAULT_CRC_DIGITS = 2;
@@ -80,9 +80,6 @@ const calcCrc = (data, crcDigits) => {
 /**
  * @typedef {ReturnType<typeof initDurableBoardState>} BoardState // TODO: use
  *   Key from @agoric/store when available
- * @import {Passable} from '@endo/marshal'
- * @see {prepareExoClassKit}
- * @see {@link ../../SwingSet/docs/virtual-objects.md|SwingSet Virtual Objects} Hoisting this function makes defining the state type concise.
  */
 
 // TODO consider tightening initSequence to bigint only

diff --git a/packages/vats/src/vat-bank.js b/packages/vats/src/vat-bank.js
@@ -22,8 +22,9 @@ import {
 } from './virtual-purse.js';
 
 /**
- * @import {Guarded} from '@endo/exo')
- * @import {Passable, RemotableObject} from '@endo/pass-style')
+ * @import {Guarded} from '@endo/exo';
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {VirtualPurseController} from './virtual-purse.js';
  */
 
 const { VirtualPurseControllerI } = makeVirtualPurseKitIKit();
@@ -37,7 +38,6 @@ const BridgeChannelI = M.interface('BridgeChannel', {
 
 /**
  * @typedef {Awaited<ReturnType<ReturnType<typeof prepareVirtualPurse>>>} VirtualPurse
- * @import {VirtualPurseController} from './virtual-purse.js'
  */
 
 /**