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/zoe/jsconfig.json

@@ -1,7 +1,7 @@
 // This file can contain .js-specific Typescript compiler config.
 {
   "compilerOptions": {
-    "target": "es2020",
+    "target": "esnext",
 
     "noEmit": true,
 /*

packages/zoe/package.json

@@ -12,7 +12,8 @@
     "build-zcfBundle": "node -r esm scripts/build-zcfBundle.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'"
@@ -73,8 +74,10 @@
   "eslintConfig": {
     "extends": [
       "airbnb-base",
-      "plugin:prettier/recommended"
+      "plugin:prettier/recommended",
+      "plugin:jsdoc/recommended"
     ],
+    "parser": "@typescript-eslint/parser",
     "env": {
       "es6": true
     },
@@ -105,7 +108,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"
     }
   },
   "eslintIgnore": [

packages/zoe/src/cleanProposal.js

@@ -98,6 +98,7 @@ export const cleanKeywords = keywordRecord => {
  * `exit`, if present, must be a record of one of the following forms:
  * `{ waived: null }` `{ onDemand: null }` `{ afterDeadline: { timer
  * :Timer, deadline :Number } }
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath
  * @param {Proposal} proposal
  * @returns {ProposalRecord}

packages/zoe/src/contractFacet/contractFacet.js

@@ -31,23 +31,23 @@ import '../../exported';
 import '../internal-types';
 
 export function buildRootObject(_powers, _params, testJigSetter = undefined) {
-  /** @type ExecuteContract */
+  /** @type {ExecuteContract} */
   const executeContract = async (
     bundle,
     zoeService,
     invitationIssuer,
     zoeInstanceAdmin,
     instanceRecord,
   ) => {
-    /** @type IssuerTable */
+    /** @type {IssuerTable} */
     const issuerTable = makeIssuerTable();
     const getAmountMath = brand => issuerTable.getByBrand(brand).amountMath;
 
     const invitationHandleToHandler = makeWeakStore('invitationHandle');
 
-    /** @type WeakStore<ZCFSeat,ZCFSeatAdmin> */
+    /** @type {WeakStore<ZCFSeat,ZCFSeatAdmin>} */
     const zcfSeatToZCFSeatAdmin = makeWeakStore('zcfSeat');
-    /** @type WeakStore<ZCFSeat,SeatHandle> */
+    /** @type {WeakStore<ZCFSeat,SeatHandle>} */
     const zcfSeatToSeatHandle = makeWeakStore('zcfSeat');
 
     const keywords = Object.keys(instanceRecord.terms.issuers);
@@ -56,7 +56,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
     const initIssuers = issuersP =>
       Promise.all(issuersP.map(issuerTable.initIssuer));
 
-    /** @type RegisterIssuerRecord */
+    /** @type {RegisterIssuerRecord} */
     const registerIssuerRecord = (keyword, issuerRecord) => {
       instanceRecord = {
         ...instanceRecord,
@@ -80,7 +80,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
       return issuerRecord;
     };
 
-    /** @type RegisterIssuerRecordWithKeyword */
+    /** @type {RegisterIssuerRecordWithKeyword} */
     const registerIssuerRecordWithKeyword = (keyword, issuerRecord) => {
       assertKeywordName(keyword);
       assert(
@@ -101,6 +101,8 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
      * Unlike the zcf.reallocate method, this one does not check conservation,
      * and so can be used internally for reallocations that violate
      * conservation.
+     *
+     * @param {SeatStaging[]} seatStagings
      */
     const reallocateInternal = seatStagings => {
       // Keep track of seats used so far in this call, to prevent aliasing.
@@ -143,7 +145,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
       E(zoeInstanceAdmin).replaceAllocations(seatHandleAllocations);
     };
 
-    /** @type MakeZCFMint */
+    /** @type {MakeZCFMint} */
     const makeZCFMint = async (keyword, amountMathKind = MathKind.NAT) => {
       assert(
         !(keyword in instanceRecord.terms.issuers),
@@ -164,7 +166,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
       registerIssuerRecordWithKeyword(keyword, mintyIssuerRecord);
       issuerTable.initIssuerByRecord(mintyIssuerRecord);
 
-      /** @type ZCFMint */
+      /** @type {ZCFMint} */
       const zcfMint = harden({
         getIssuerRecord: () => {
           return mintyIssuerRecord;
@@ -232,9 +234,9 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
       return zcfMint;
     };
 
-    /** @type ContractFacet */
+    /** @type {ContractFacet} */
     const zcf = {
-      reallocate: (/** @type SeatStaging[] */ ...seatStagings) => {
+      reallocate: (/** @type {SeatStaging[]} */ ...seatStagings) => {
         // We may want to handle this with static checking instead.
         // Discussion at: https://github.com/Agoric/agoric-sdk/issues/1017
         assert(
@@ -364,7 +366,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
        * will be appended to the returned jig object (overriding any
        * provided by the `testFn`).
        *
-       * @type SetTestJig
+       * @type {SetTestJig}
        */
       setTestJig: (testFn = () => ({})) => {
         if (testJigSetter) {
@@ -377,7 +379,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
 
     // addSeatObject gives Zoe the ability to notify ZCF when a new seat is
     // added in offer(). ZCF responds with the exitObj and offerResult.
-    /** @type AddSeatObj */
+    /** @type {AddSeatObj} */
     const addSeatObj = {
       addSeat: (invitationHandle, zoeSeatAdmin, seatData, seatHandle) => {
         const { zcfSeatAdmin, zcfSeat } = makeZcfSeatAdminKit(
@@ -398,7 +400,7 @@ export function buildRootObject(_powers, _params, testJigSetter = undefined) {
           zoeSeatAdmin,
           zcfSeatAdmin,
         );
-        /** @type AddSeatResult */
+        /** @type {AddSeatResult} */
         return harden({ offerResultP, exitObj });
       },
     };

packages/zoe/src/contractFacet/exit.js

@@ -6,7 +6,7 @@ import { E } from '@agoric/eventual-send';
  * to request the position be exited.
  */
 
-/** @type MakeExitObj */
+/** @type {MakeExitObj} */
 export const makeExitObj = (proposal, zoeSeatAdmin, zcfSeatAdmin) => {
   const [exitKind] = Object.getOwnPropertyNames(proposal.exit);
 

packages/zoe/src/contractFacet/offerSafety.js

@@ -4,6 +4,7 @@
  * Helper to perform satisfiesWant and satisfiesGive. Is
  * allocationAmount greater than or equal to requiredAmount for every
  * keyword of giveOrWant?
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath
  * @param {AmountKeywordRecord} giveOrWant
  * @param {AmountKeywordRecord} allocation
@@ -25,6 +26,7 @@ const satisfiesInternal = (getAmountMath, giveOrWant = {}, allocation) => {
 /**
  * For this allocation to satisfy what the user wanted, their
  * allocated amounts must be greater than or equal to proposal.want.
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath - a
  * function that takes a brand and returns the appropriate amountMath.
  * The function must have an amountMath for every brand in
@@ -46,6 +48,7 @@ const satisfiesWant = (getAmountMath, proposal, allocation) =>
  * For this allocation to count as a full refund, the allocated
  * amounts must be greater than or equal to what was originally
  * offered (proposal.give).
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath - a
  * function that takes a brand and returns the appropriate amountMath.
  * The function must have an amountMath for every brand in

packages/zoe/src/contractFacet/rightsConservation.js

@@ -9,6 +9,7 @@ import '../internal-types';
 /**
  * Iterate over the amounts and sum, storing the sums in a
  * map by brand.
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath - a function
  * to get amountMath given a brand.
  * @param  {Amount[]} amounts - an array of amounts
@@ -31,6 +32,7 @@ const sumByBrand = (getAmountMath, amounts) => {
 
 /**
  * Assert that the left sums by brand equal the right sums by brand
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath - a function
  * to get amountMath given a brand.
  * @param  {Store<Brand, Amount>} leftSumsByBrand - a map of brands to sums
@@ -65,6 +67,7 @@ const assertEqualPerBrand = (
 /**
  * `assertRightsConserved` checks that the total amount per brand is
  * equal to the total amount per brand in the proposed reallocation
+ *
  * @param {(brand: Brand) => AmountMath} getAmountMath - a function
  * to get amountMath given a brand.
  * @param  {Amount[]} previousAmounts - an array of the amounts before the

packages/zoe/src/contractFacet/types.js

@@ -26,7 +26,7 @@
  * @property {(brand: Brand) => Issuer} getIssuerForBrand
  * @property {GetAmountMath} getAmountMath
  * @property {MakeZCFMint} makeZCFMint
- * @property {(exit?: ExitRule) => ZcfSeatKit} makeEmptySeatKit
+ * @property {(exit: ExitRule=) => ZcfSeatKit} makeEmptySeatKit
  * @property {SetTestJig} setTestJig
  */
 
@@ -102,15 +102,15 @@
 
 /**
  * @callback SetTestJig
- * @param {() => any=() => {}} testFn
+ * @param {() => any} testFn
  * @returns {void}
  */
 
 /**
  * @typedef {Object} ZCFMint
  * @property {() => IssuerRecord} getIssuerRecord
  * @property {(gains: AmountKeywordRecord,
- *             zcfSeat?: ZCFSeat,
+ *             zcfSeat: ZCFSeat=,
  *            ) => ZCFSeat} mintGains
  * All the amounts in gains must be of this ZCFMint's brand.
  * The gains' keywords are in the namespace of that seat.
@@ -138,7 +138,7 @@
 /**
  * @typedef {Object} ZCFSeat
  * @property {() => void} exit
- * @property {(reason?: Error) => Error} kickOut called with the reason this
+ * @property {(reason: Error=) => Error} kickOut called with the reason this
  * seat is being kicked out, where reason is normally an instanceof Error.
  * @property {() => Notifier<Allocation>} getNotifier
  * @property {() => boolean} hasExited
@@ -147,7 +147,7 @@
  * The brand is used for filling in an empty amount if the `keyword`
  * is not present in the allocation
  * @property {() => Allocation} getCurrentAllocation
- * @property {(newAllocation: Allocation) => Boolean} isOfferSafe
+ * @property {(newAllocation: Allocation) => boolean} isOfferSafe
  * @property {(newAllocation: Allocation) => SeatStaging} stage
  */
 

packages/zoe/src/contractSupport/bondingCurves.js

@@ -14,6 +14,7 @@ const { add, subtract, multiply, floorDivide } = natSafeMath;
  * is valid, getting the current price for an asset on user
  * request, and to do the actual reallocation after an offer has
  * been made.
+ *
  * @param {Object} params
  * @param  {number} params.inputValue - the value of the asset sent
  * in to be swapped
@@ -47,6 +48,7 @@ export const getInputPrice = ({
  * is valid, getting the current price for an asset on user
  * request, and to do the actual reallocation after an offer has
  * been made.
+ *
  * @param {Object} params
  * @param  {number} params.outputValue - the value of the asset the user wants
  * to get
@@ -106,10 +108,10 @@ export const calcLiqValueToMint = ({
  * match the current ratio of holdings in the pool.
  *
  * @param {Object} params
- * @param params.centralIn - The value of central assets being deposited
- * @param params.centralPool - The value of central assets in the pool
- * @param params.secondaryPool - The value of secondary assets in the pool
- * @param params.secondaryIn - The value of secondary assets provided. If
+ * @param {number} params.centralIn - The value of central assets being deposited
+ * @param {number} params.centralPool - The value of central assets in the pool
+ * @param {number} params.secondaryPool - The value of secondary assets in the pool
+ * @param {number} params.secondaryIn - The value of secondary assets provided. If
  * the pool is empty, the entire amount will be accepted
  * @returns {number} - the amount of secondary required
  */

packages/zoe/src/contractSupport/zoeHelpers.js

@@ -20,6 +20,7 @@ const getKeysSorted = obj =>
  * toGains will be added to 'to'. If fromLosses is defined, all the
  * entries in fromLosses are subtracted from 'from'. (If fromLosses
  * is not defined, toGains is subtracted from 'from'.)
+ *
  * @param {ContractFacet} zcf
  * @param {FromToAllocations} allocations - the 'to' and 'from'
  * allocations
@@ -100,6 +101,7 @@ export const assertIssuerKeywords = (zcf, expected) => {
  * checked. The update is merged with currentAllocation
  * (update's values prevailing if the keywords are the same)
  * to produce the newAllocation.
+ *
  * @param {ContractFacet} zcf
  * @param {ZCFSeat} seat
  * @param {AmountKeywordRecord} update
@@ -186,7 +188,7 @@ export const trade = (
   }
 };
 
-/** @type Swap */
+/** @type {Swap} */
 export const swap = (
   zcf,
   leftSeat,
@@ -220,7 +222,7 @@ export const swap = (
 };
 
 /**
- * @type Swap
+ * @type {Swap}
  * Swap such that both seats gain what they want and lose everything
  * that they gave. Only good for exact and entire swaps where each
  * seat wants everything that the other seat has. The benefit of using
@@ -260,12 +262,14 @@ export const swapExact = (
   return defaultAcceptanceMsg;
 };
 
+/* eslint-disable jsdoc/valid-types */
 /**
  * @typedef ExpectedRecord
  * @property {Record<Keyword, null>} [want]
  * @property {Record<Keyword, null>} [give]
  * @property {Partial<Record<keyof ProposalRecord['exit'], null>>} [exit]
  */
+/* eslint-enable jsdoc/valid-types */
 
 /**
  * Check the seat's proposal against an `expected` record that says
@@ -374,6 +378,7 @@ export async function withdrawFromSeat(zcf, seat, amounts) {
  * Save all of the issuers in an issuersKeywordRecord to ZCF, using
  * the method `zcf.saveIssuer`. This does not error if any of the keywords
  * already exist. If the keyword is already present, it is ignored.
+ *
  * @param {ContractFacet} zcf
  * @param {IssuerKeywordRecord} issuerKeywordRecord Issuers to save to
  * ZCF

packages/zoe/src/contracts/automaticRefund.js

@@ -13,6 +13,7 @@ import '../../exported';
  * Since the contract doesn't attempt any reallocation, the offer can contain
  * anything in `give` and `want`. The amount in `give` will be returned, and
  * `want` will be ignored.
+ *
  * @type {ContractStartFn}
  * @param {ContractFacet} zcf
  */