Skip to content

Commit

Permalink
Merge pull request #4906 from Agoric/4900-autoformat-jsdoc-run-protocol
Browse files Browse the repository at this point in the history 
autoformat jsdoc of some packages
  • Loading branch information
@turadg @mhofman
turadg authored and mhofman committed Aug 7, 2023
2 parents b21bdc8 + 8d191f4 commit cf12a1e
Show file tree
Hide file tree
Showing 155 changed files with 3,516 additions and 2,647 deletions.
21 changes: 20 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,17 +26,36 @@
"eslint-plugin-github": "^4.8.0",
"eslint-plugin-import": "^2.25.3",
"eslint-plugin-jsdoc": "^46.4.3",
"eslint-plugin-prettier": "^5.0.0-alpha.2",
"eslint-plugin-prettier": "^5.0.0",
"lerna": "^3.22.1",
"npm-run-all": "^4.1.5",
"prettier": "^3.0.0",
"prettier-plugin-jsdoc": "^1.0.0",
"typescript": "~5.1.6"
},
"engines": {
"node": "^16.13 || ^18.12"
},
"prettier": {
"arrowParens": "avoid",
"overrides": [
{
"files": [
"packages/ERTP/**/*.{js,ts}",
"packages/inter-protocol/**/*.{js,ts}",
"packages/vats/**/*.{js,ts}"
],
"options": {
"plugins": [
"prettier-plugin-jsdoc"
],
"jsdocAddDefaultToDescription": false,
"jsdocParser": true,
"jsdocCapitalizeDescription": false,
"tsdoc": true
}
}
],
"singleQuote": true
},
"scripts": {
Expand Down
120 changes: 57 additions & 63 deletions packages/ERTP/src/amountMath.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,12 @@ const { quote: q, Fail } = assert;
/**
* Constants for the kinds of assets we support.
*
* @type {{ NAT: 'nat', SET: 'set', COPY_SET: 'copySet', COPY_BAG: 'copyBag' }}
* @type {{
* NAT: 'nat';
* SET: 'set';
* COPY_SET: 'copySet';
* COPY_BAG: 'copyBag';
* }}
*/
const AssetKind = harden({
NAT: 'nat',
Expand All @@ -21,52 +26,45 @@ const AssetKind = harden({
});
const assetKindNames = harden(Object.values(AssetKind).sort());

/**
* @param {AssetKind} allegedAK
*/
/** @param {AssetKind} allegedAK */
const assertAssetKind = allegedAK => {
assetKindNames.includes(allegedAK) ||
Fail`The assetKind ${allegedAK} must be one of ${q(assetKindNames)}`;
};
harden(assertAssetKind);

/**
* Amounts describe digital assets. From an amount, you can learn the
* brand of digital asset as well as "how much" or "how many". Amounts
* have two parts: a brand (loosely speaking, the type of digital
* asset) and the value (the answer to "how much"). For example, in
* the phrase "5 bucks", "bucks" takes the role of the brand and the
* value is 5. Amounts can describe fungible and non-fungible digital
* assets. Amounts are pass-by-copy and can be made by and sent to
* anyone.
* Amounts describe digital assets. From an amount, you can learn the brand of
* digital asset as well as "how much" or "how many". Amounts have two parts: a
* brand (loosely speaking, the type of digital asset) and the value (the answer
* to "how much"). For example, in the phrase "5 bucks", "bucks" takes the role
* of the brand and the value is 5. Amounts can describe fungible and
* non-fungible digital assets. Amounts are pass-by-copy and can be made by and
* sent to anyone.
*
* The issuer is the authoritative source of the amount in payments
* and purses. The issuer must be able to do things such as add
* digital assets to a purse and withdraw digital assets from a purse.
* To do so, it must know how to add and subtract digital assets.
* Rather than hard-coding a particular solution, we chose to
* parameterize the issuer with a collection of polymorphic functions,
* which we call `AmountMath`. These math functions include concepts
* The issuer is the authoritative source of the amount in payments and purses.
* The issuer must be able to do things such as add digital assets to a purse
* and withdraw digital assets from a purse. To do so, it must know how to add
* and subtract digital assets. Rather than hard-coding a particular solution,
* we chose to parameterize the issuer with a collection of polymorphic
* functions, which we call `AmountMath`. These math functions include concepts
* like addition, subtraction, and greater than or equal to.
*
* We also want to make sure there is no confusion as to what kind of
* asset we are using. Thus, AmountMath includes checks of the
* `brand`, the unique identifier for the type of digital asset. If
* the wrong brand is used in AmountMath, an error is thrown and the
* operation does not succeed.
* We also want to make sure there is no confusion as to what kind of asset we
* are using. Thus, AmountMath includes checks of the `brand`, the unique
* identifier for the type of digital asset. If the wrong brand is used in
* AmountMath, an error is thrown and the operation does not succeed.
*
* AmountMath uses mathHelpers to do most of the work, but then adds
* the brand to the result. The function `value` gets the value from
* the amount by removing the brand (amount -> value), and the
* function `make` adds the brand to produce an amount (value ->
* amount). The function `coerce` takes an amount and checks it,
* returning an amount (amount -> amount).
* AmountMath uses mathHelpers to do most of the work, but then adds the brand
* to the result. The function `value` gets the value from the amount by
* removing the brand (amount -> value), and the function `make` adds the brand
* to produce an amount (value -> amount). The function `coerce` takes an amount
* and checks it, returning an amount (amount -> amount).
*
* Each issuer of digital assets has an associated brand in a
* one-to-one mapping. In untrusted contexts, such as in analyzing
* payments and amounts, we can get the brand and find the issuer
* which matches the brand. The issuer and the brand mutually validate
* each other.
* Each issuer of digital assets has an associated brand in a one-to-one
* mapping. In untrusted contexts, such as in analyzing payments and amounts, we
* can get the brand and find the issuer which matches the brand. The issuer and
* the brand mutually validate each other.
*/

const helpers = {
Expand Down Expand Up @@ -137,7 +135,7 @@ const optionalBrandCheck = (allegedBrand, brand) => {
* @param {Amount<K>} leftAmount
* @param {Amount<K>} rightAmount
* @param {Brand<K> | undefined} brand
* @returns {MathHelpers<*>}
* @returns {MathHelpers<any>}
*/
const checkLRAndGetHelpers = (leftAmount, rightAmount, brand = undefined) => {
assertRecord(leftAmount, 'leftAmount');
Expand Down Expand Up @@ -172,11 +170,11 @@ const coerceLR = (h, leftAmount, rightAmount) => {
};

/**
* Returns true if the leftAmount is greater than or equal to the
* rightAmount. The notion of "greater than or equal to" depends
* on the kind of amount, as defined by the MathHelpers. For example,
* whether rectangle A is greater than rectangle B depends on whether rectangle
* A includes rectangle B as defined by the logic in MathHelpers.
* Returns true if the leftAmount is greater than or equal to the rightAmount.
* The notion of "greater than or equal to" depends on the kind of amount, as
* defined by the MathHelpers. For example, whether rectangle A is greater than
* rectangle B depends on whether rectangle A includes rectangle B as defined by
* the logic in MathHelpers.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -194,9 +192,8 @@ const isGTE = (leftAmount, rightAmount, brand = undefined) => {
*
* Amounts are the canonical description of tradable goods. They are manipulated
* by issuers and mints, and represent the goods and currency carried by purses
* and
* payments. They can be used to represent things like currency, stock, and the
* abstract right to participate in a particular exchange.
* and payments. They can be used to represent things like currency, stock, and
* the abstract right to participate in a particular exchange.
*/
const AmountMath = {
/**
Expand All @@ -215,8 +212,8 @@ const AmountMath = {
return harden({ brand, value });
},
/**
* Make sure this amount is valid enough, and return a corresponding
* valid amount if so.
* Make sure this amount is valid enough, and return a corresponding valid
* amount if so.
*
* @template {AssetKind} K
* @param {Brand<K>} brand
Expand All @@ -242,8 +239,8 @@ const AmountMath = {
*/
getValue: (brand, amount) => AmountMath.coerce(brand, amount).value,
/**
* Return the amount representing an empty amount. This is the
* identity element for MathHelpers.add and MatHelpers.subtract.
* Return the amount representing an empty amount. This is the identity
* element for MathHelpers.add and MatHelpers.subtract.
*
* @type {{
* (brand: Brand): Amount<'nat'>;
Expand All @@ -257,8 +254,8 @@ const AmountMath = {
return harden({ brand, value });
},
/**
* Return the amount representing an empty amount, using another
* amount as the template for the brand and assetKind.
* Return the amount representing an empty amount, using another amount as the
* template for the brand and assetKind.
*
* @template {AssetKind} K
* @param {Amount<K>} amount
Expand Down Expand Up @@ -289,8 +286,8 @@ const AmountMath = {
},
isGTE,
/**
* Returns true if the leftAmount equals the rightAmount. We assume
* that if isGTE is true in both directions, isEqual is also true
* Returns true if the leftAmount equals the rightAmount. We assume that if
* isGTE is true in both directions, isEqual is also true
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -306,8 +303,8 @@ const AmountMath = {
* Returns a new amount that is the union of both leftAmount and rightAmount.
*
* For fungible amount this means adding the values. For other kinds of
* amount, it usually means including all of the elements from both
* left and right.
* amount, it usually means including all of the elements from both left and
* right.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand All @@ -321,12 +318,11 @@ const AmountMath = {
return harden({ brand: leftAmount.brand, value });
},
/**
* Returns a new amount that is the leftAmount minus the rightAmount
* (i.e. everything in the leftAmount that is not in the
* rightAmount). If leftAmount doesn't include rightAmount
* (subtraction results in a negative), throw an error. Because the
* left amount must include the right amount, this is NOT equivalent
* to set subtraction.
* Returns a new amount that is the leftAmount minus the rightAmount (i.e.
* everything in the leftAmount that is not in the rightAmount). If leftAmount
* doesn't include rightAmount (subtraction results in a negative), throw an
* error. Because the left amount must include the right amount, this is NOT
* equivalent to set subtraction.
*
* @template {AssetKind} K
* @param {Amount<K>} leftAmount
Expand Down Expand Up @@ -374,9 +370,7 @@ const AmountMath = {
};
harden(AmountMath);

/**
* @param {Amount} amount
*/
/** @param {Amount} amount */
const getAssetKind = amount => {
assertRecord(amount, 'amount');
const { value } = amount;
Expand Down
Loading

0 comments on commit cf12a1e

Please sign in to comment.