Merge pull request #1746 from Agoric/mfig/eslint-jsdoc

refactor: have ESLint manage our JSDocs

package.json

@@ -42,13 +42,15 @@
     "packages/xs-vat-worker"
   ],
   "devDependencies": {
+    "@typescript-eslint/parser": "^4.1.0",
     "ava": "^3.12.1",
     "eslint": "^6.8.0",
     "eslint-config-airbnb": "^18.0.1",
     "eslint-config-airbnb-base": "^14.0.0",
     "eslint-config-jessie": "^0.0.4",
     "eslint-config-prettier": "^6.9.0",
     "eslint-plugin-import": "^2.20.0",
+    "eslint-plugin-jsdoc": "^30.4.2",
     "eslint-plugin-jsx-a11y": "^6.2.3",
     "eslint-plugin-prettier": "^3.1.2",
     "lerna": "^3.20.2",

packages/ERTP/package.json

@@ -14,7 +14,8 @@
     "pretty-check": "prettier --check '**/*.js'",
     "lint-fix": "yarn lint --fix",
     "lint-check": "yarn lint",
-    "lint": "yarn lint:types && eslint '**/*.js'",
+    "lint": "yarn lint:types && yarn lint:eslint",
+    "lint:eslint": "eslint '**/*.js'",
     "lint:types": "tsc -p jsconfig.json",
     "lint-fix-jessie": "eslint -c '.eslintrc-jessie.js' --fix '**/*.js'",
     "lint-check-jessie": "eslint -c '.eslintrc-jessie.js' '**/*.js'"
@@ -71,8 +72,10 @@
   "eslintConfig": {
     "extends": [
       "airbnb-base",
-      "plugin:prettier/recommended"
+      "plugin:prettier/recommended",
+      "plugin:jsdoc/recommended"
     ],
+    "parser": "@typescript-eslint/parser",
     "env": {
       "es6": true
     },
@@ -103,7 +106,13 @@
       "no-unused-expressions": "off",
       "no-loop-func": "off",
       "no-inner-declarations": "off",
-      "import/prefer-default-export": "off"
+      "import/prefer-default-export": "off",
+      "jsdoc/no-undefined-types": "off",
+      "jsdoc/require-jsdoc": "off",
+      "jsdoc/require-property-description": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns": "off",
+      "jsdoc/require-returns-description": "off"
     }
   },
   "prettier": {

packages/ERTP/src/amountMath.js

@@ -12,6 +12,7 @@ import setMathHelpers from './mathHelpers/setMathHelpers';
 // We want an enum, but narrowed to the AmountMathKind type.
 /**
  * Constants for the kinds of amountMath we support.
+ *
  * @type {{ NAT: 'nat', SET: 'set', STRING_SET: 'strSet' }}
  */
 const MathKind = {
@@ -99,6 +100,7 @@ function makeAmountMath(brand, amountMathKind) {
 
     /**
      * Make an amount from a value by adding the brand.
+     *
      * @param {Value} allegedValue
      * @returns {Amount}
      */
@@ -111,6 +113,7 @@ function makeAmountMath(brand, amountMathKind) {
 
     /**
      * Make sure this amount is valid and return it if so, throwing if invalid.
+     *
      * @param {Amount} allegedAmount
      * @returns {Amount} or throws if invalid
      */

packages/ERTP/src/mathHelpers/natMathHelpers.js

@@ -15,6 +15,7 @@ const identity = 0;
  * rounding issues make floats problematic. All operations should be
  * done with the smallest whole unit such that the NatMathHelpers never
  * deals with fractional parts.
+ *
  * @type {MathHelpers}
  */
 const natMathHelpers = harden({

packages/ERTP/src/types.js

@@ -144,15 +144,15 @@
  *
  * If the payment is a promise, the operation will proceed upon resolution.
  *
- * @property {(payment: PaymentP, optAmount?: Amount) => Promise<Amount>} burn
+ * @property {(payment: PaymentP, optAmount: Amount=) => Promise<Amount>} burn
  * Burn all of the digital assets in the payment. `optAmount` is optional.
  * If `optAmount` is present, the code will insist that the amount of
  * the digital assets in the payment is equal to `optAmount`, to
  * prevent sending the wrong payment and other confusion.
  *
  * If the payment is a promise, the operation will proceed upon resolution.
  *
- * @property {(payment: PaymentP, optAmount?: Amount) => Promise<Payment>} claim
+ * @property {(payment: PaymentP, optAmount: Amount=) => Promise<Payment>} claim
  * Transfer all digital assets from the payment to a new payment and
  * delete the original. `optAmount` is optional.
  * If `optAmount` is present, the code will insist that the amount of
@@ -216,7 +216,7 @@
 
 /**
  * @typedef {Object} DepositFacet
- * @property {(payment: Payment, optAmount?: Amount) => Amount} receive
+ * @property {(payment: Payment, optAmount: Amount=) => Amount} receive
  * Deposit all the contents of payment into the purse that made this facet,
  * returning the amount. If the optional argument `optAmount` does not equal the
  * amount of digital assets in the payment, throw an error.
@@ -240,7 +240,7 @@
  * @property {() => Amount} getCurrentAmount
  * Get the amount contained in this purse.
  *
- * @property {(payment: Payment, optAmount?: Amount) => Amount} deposit
+ * @property {(payment: Payment, optAmount: Amount=) => Amount} deposit
  * Deposit all the contents of payment into this purse, returning the
  * amount. If the optional argument `optAmount` does not equal the
  * amount of digital assets in the payment, throw an error.

packages/assert/package.json

@@ -12,7 +12,8 @@
     "test:nyc": "nyc ava",
     "lint-fix": "yarn lint --fix",
     "lint-check": "yarn lint",
-    "lint": "yarn lint:types && eslint '**/*.js'",
+    "lint": "yarn lint:types && yarn lint:eslint",
+    "lint:eslint": "eslint '**/*.js'",
     "lint:types": "tsc -p jsconfig.json",
     "lint-fix-jessie": "eslint -c '.eslintrc-jessie.js' --fix '**/*.js'",
     "lint-check-jessie": "eslint -c '.eslintrc-jessie.js' '**/*.js'"
@@ -52,8 +53,10 @@
   "eslintConfig": {
     "extends": [
       "airbnb-base",
-      "plugin:prettier/recommended"
+      "plugin:prettier/recommended",
+      "plugin:jsdoc/recommended"
     ],
+    "parser": "@typescript-eslint/parser",
     "env": {
       "es6": true
     },
@@ -84,7 +87,14 @@
       "no-unused-expressions": "off",
       "no-loop-func": "off",
       "no-inner-declarations": "off",
-      "import/prefer-default-export": "off"
+      "import/prefer-default-export": "off",
+      "import/no-extraneous-dependencies": "off",
+      "jsdoc/no-undefined-types": "off",
+      "jsdoc/require-jsdoc": "off",
+      "jsdoc/require-property-description": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns": "off",
+      "jsdoc/require-returns-description": "off"
     }
   },
   "eslintIgnore": [

packages/assert/src/assert.js

@@ -35,6 +35,8 @@ harden(an);
  * The current `cycleTolerantStringify` possibly emits too many "seen"
  * markings: Not only for cycles, but also for repeated subtrees by
  * object identity.
+ *
+ * @param {any} payload
  */
 function cycleTolerantStringify(payload) {
   const seenSet = new Set();
@@ -177,8 +179,8 @@ harden(details);
  *
  * The optional `optDetails` can be a string for backwards compatibility
  * with the nodejs assertion library.
+ *
  * @param {Details} [optDetails] The details of what was asserted
- * @returns {never}
  */
 function fail(optDetails = details`Assert failed`) {
   if (typeof optDetails === 'string') {
@@ -189,11 +191,13 @@ function fail(optDetails = details`Assert failed`) {
   throw optDetails.complain();
 }
 
+/* eslint-disable jsdoc/require-returns-check,jsdoc/valid-types */
 /**
  * @param {*} flag The truthy/falsy value
  * @param {Details} [optDetails] The details to throw
  * @returns {asserts flag}
  */
+/* eslint-enable jsdoc/require-returns-check,jsdoc/valid-types */
 function assert(flag, optDetails = details`Check failed`) {
   if (!flag) {
     throw fail(optDetails);
@@ -202,6 +206,7 @@ function assert(flag, optDetails = details`Check failed`) {
 
 /**
  * Assert that two values must be `Object.is`.
+ *
  * @param {*} actual The value we received
  * @param {*} expected What we wanted
  * @param {Details} [optDetails] The details to throw
@@ -217,6 +222,7 @@ function equal(
 
 /**
  * Assert an expected typeof result.
+ *
  * @type {AssertTypeof}
  * @param {any} specimen The value to get the typeof
  * @param {string} typename The expected name
@@ -239,6 +245,7 @@ const assertTypeof = (specimen, typename, optDetails) => {
   equal(typeof specimen, typename, optDetails);
 };
 
+/* eslint-disable jsdoc/valid-types */
 /**
  * assert that expr is truthy, with an optional details to describe
  * the assertion. It is a tagged template literal like
@@ -258,8 +265,10 @@ const assertTypeof = (specimen, typename, optDetails) => {
  *
  * The optional `optDetails` can be a string for backwards compatibility
  * with the nodejs assertion library.
+ *
  * @type {typeof assert & { typeof: AssertTypeof, fail: typeof fail, equal: typeof equal }}
  */
+/* eslint-enable jsdoc/valid-types */
 const assertCombined = Object.assign(assert, {
   equal,
   fail,

packages/assert/src/types.js

@@ -4,6 +4,7 @@
 // Type all the overloads of the assertTypeof function.
 // There may eventually be a better way to do this, but
 // thems the breaks with Typescript 4.0.
+/* eslint-disable jsdoc/valid-types */
 /**
  * @callback AssertTypeofBigint
  * @param {any} specimen
@@ -53,6 +54,7 @@
  * @param {Details} [optDetails]
  * @returns {asserts specimen is undefined}
  */
+/* eslint-enable jsdoc/valid-types */
 
 /**
  * @typedef {AssertTypeofBigint & AssertTypeofBoolean & AssertTypeofFunction & AssertTypeofNumber & AssertTypeofObject & AssertTypeofString & AssertTypeofSymbol & AssertTypeofUndefined} AssertTypeof

packages/cosmic-swingset/lib/ag-solo/chain-cosmos-sdk.js

@@ -317,6 +317,7 @@ ${chainID} chain does not yet know of address ${myAddr}${adviseProvision(
 
   /**
    * Get a notifier that announces every time a block lands.
+   *
    * @returns {Notifier<any>}
    */
   const getBlockNotifier = () => {

packages/cosmic-swingset/lib/ag-solo/vats/bootstrap.js

@@ -1,5 +1,3 @@
-/* global harden */
-
 import { allComparable } from '@agoric/same-structure';
 import {
   makeLoopbackProtocolHandler,

packages/cosmic-swingset/lib/ag-solo/vats/bridge.js

@@ -1,11 +1,10 @@
-/* global harden */
 // @ts-check
 
 import makeStore from '@agoric/store';
 
 /**
  * @template T
- * @typedef {Object} Device
+ * @typedef {'Device' & { __deviceType__: T }} Device
  */
 
 /**
@@ -25,6 +24,7 @@ import makeStore from '@agoric/store';
  * @property {(srcID: string, handler: BridgeHandler) => void} unregister
  */
 
+/* eslint-disable jsdoc/valid-types */
 /**
  * Create a handler that demuxes/muxes the bridge device by its first argument.
  *
@@ -33,6 +33,7 @@ import makeStore from '@agoric/store';
  * @param {Device<BridgeDevice>} bridgeDevice The bridge to manage
  * @returns {BridgeManager} admin facet for this handler
  */
+/* eslint-enable jsdoc/valid-types */
 export function makeBridgeManager(E, D, bridgeDevice) {
   /**
    * @type {import('@agoric/store').Store<string, BridgeHandler>}

packages/cosmic-swingset/lib/ag-solo/vats/captp.js

@@ -1,5 +1,3 @@
-/* global harden */
-
 // Avoid importing the full captp bundle, which would carry
 // in its own makeHardener, etc.
 import { makeCapTP } from '@agoric/captp/lib/captp';

packages/cosmic-swingset/lib/ag-solo/vats/ibc.js

@@ -1,4 +1,3 @@
-/* global harden */
 // @ts-check
 
 import {
@@ -55,6 +54,7 @@ const FIXME_ALLOW_NAIVE_RELAYS = true;
 const goodLetters = 'abcdefghijklmnopqrstuvwxyz';
 /**
  * Get a sequence of letters chosen from `goodLetters`.
+ *
  * @param {number} n
  */
 function getGoodLetters(n) {
@@ -145,6 +145,7 @@ export function makeIBCProtocolHandler(E, callIBCDevice) {
 
   /**
    * Send a packet out via the IBC device.
+   *
    * @param {IBCPacket} packet
    * @param {Store<number, PromiseRecord<Bytes, any>>} seqToAck
    */

packages/cosmic-swingset/lib/ag-solo/vats/lib-board.js

@@ -1,5 +1,4 @@
 // @ts-check
-/* global harden */
 
 import { generateSparseInts } from '@agoric/sparse-ints';
 import { assert, details, q } from '@agoric/assert';
@@ -11,8 +10,9 @@ const ID_REGEXP = new RegExp(`^[0-9]{${CRC_NUM_DIGITS + 1},}$`);
 
 /**
  * We calculate a CRC, ensuring it's of CRC_NUM_DIGITS length.
+ *
  * @param {number} num
- * @return {string}
+ * @returns {string}
  */
 const calcCrc = num => {
   // The explicit use of crcmodels is to avoid a typing error.
@@ -31,11 +31,12 @@ const calcCrc = num => {
  * @property {(id: string) => any} getValue
  * @property {(value: any) => string} getId
  * @property {(value: any) => boolean} has
- * @property {() => string[]} ids```
+ * @property {() => string[]} ids
  */
 
 /**
  * Create a board to post things on.
+ *
  * @param {number} [seed=0]
  * @returns {Board}
  */

packages/cosmic-swingset/lib/ag-solo/vats/repl.js

@@ -1,4 +1,4 @@
-/* global harden Compartment */
+/* global Compartment */
 
 import { isPromise } from '@agoric/promise-kit';
 import { E } from '@agoric/eventual-send';

packages/cosmic-swingset/lib/ag-solo/vats/scratch.js

@@ -1,5 +1,3 @@
-/* global harden */
-
 export default function makeScratchPad() {
   const map = new Map();
   async function get(idP) {