chore: Improve descriptions per code review

main/glossary/README.md

@@ -480,7 +480,7 @@ For more information, see the [JavaScript Distributed Programming Guide](/guides
 
 Proposals are records with `give`, `want`, and/or `exit` properties respectively
 expressing [offer](#offer) conditions regarding what assets will be given,
-what is expected in exchange (protected by [offer safety](#offer-safety)), and
+what is desired in exchange (protected by [offer safety](#offer-safety)), and
 an [exit rule](#exit-rule) defining how/when the offer can be canceled.
 For example:
 ```js

main/guides/zoe/contract-requirements.md

@@ -131,7 +131,7 @@ between multiple offers, or create new assets to order.
 ## Making an Invitation
 
 To create an invitation in the contract, use the Zoe Contract
-Facet method [`zcf.makeInvitation`](/reference/zoe-api/zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customproperties-proposalshape).
+Facet method [`zcf.makeInvitation(...)`](/reference/zoe-api/zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape).
 
 ## Using bundleSource
 

main/guides/zoe/proposal.md

@@ -8,12 +8,13 @@ To make an offer, you use [`E(zoe).offer(...)`](/reference/zoe-api/zoe.md#e-zoe-
 - An **invitation** to participate in this contract instance.
 - A **proposal** stating your offer conditions.
 - The **payments** escrowed for the offer, each corresponding with a **give** [Keyword](/reference/zoe-api/zoe-data-types.md#keyword) in **proposal**.
-- **offerArgs** expressing additional arguments for the **offerHandler** associated with the invitation by [`zcf.makeInvitation(...)`](/reference/zoe-api/zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customproperties-proposalshape).
+- **offerArgs** expressing additional arguments for the **offerHandler** associated with the invitation by [`zcf.makeInvitation(...)`](/reference/zoe-api/zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape).
 
 ## Invitations
 
 An [Invitation](/reference/zoe-api/zoe-data-types.md#invitation) is a special case of ERTP [Payment](/reference/ertp-api/payment.md). Each is linked to a specific contract [Instance](/reference/zoe-api/zoe-data-types.md#instance), and
-having one gives you the right to participate in that contract instance by making offers with it.
+having one gives you the right to participate in that contract instance
+by using that invitation as the first argument to `E(zoe).offer(...)`.
 
 There are two ways for contract users to get an invitation:
 - If you create the contract instance, the contract might supply a special creator invitation.

main/reference/zoe-api/user-seat.md

@@ -71,7 +71,7 @@ For example, in the [Automatic Refund](/guides/zoe/contracts/automatic-refund.md
 In the [Covered Call](/guides/zoe/contracts/covered-call.md) example, it's a call option, which is an assayable **[Invitation](./zoe-data-types.md#invitation)**
 to buy the underlying asset. Strings and invitations are the most common things returned.
 The value is the result returned by the **offerHandler** function passed
-in the first argument to [`zcf.makeInvitation(...)`](./zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customproperties-proposalshape).
+in the first argument to [`zcf.makeInvitation(...)`](./zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape).
 
 Since the contract can return whatever it wants as an offer result, there is no guarantee that the
 promise will resolve promptly.

main/reference/zoe-api/zcfmint.md

@@ -30,7 +30,7 @@ Mints the *gains* **Amount** of assets and adds them to *zcfSeat*'s **[Allocatio
 All **amounts** in *losses* must be of this **ZCFMint**'s **[Brand](/reference/ertp-api/brand.md)**
 and the *losses*' **[Keywords](./zoe-data-types.md#keyword)** must be defined by the contract instance in which *zcfSeat* is participating.
 Subtracts *losses* from *zcfSeat*'s **[Allocation](./zoe-data-types.md#allocation)**, then
-burns that **amount** of assets from the pooled **[Purse](/reference/ertp-api/purse.md)**.
+burns that **amount** from the assets escrowed by Zoe for this contract instance.
 
 
 

main/reference/zoe-api/zoe-contract-facet.md

@@ -70,10 +70,11 @@ associated with the **Issuer** value of the record:
 await zcf.saveIssuer(secondaryIssuer, keyword);
 ```
 
-## zcf.makeInvitation(offerHandler, description, customProperties?, proposalShape?)
+<a id="zcf-makeinvitation-offerhandler-description-customproperties-proposalshape"></a>
+## zcf.makeInvitation(offerHandler, description, customDetails?, proposalShape?)
 - **offerHandler**: **(seat: ZCFSeat, offerArgs?: CopyRecord) => any**
 - **description**: **String**
-- **customProperties**: **Object** - Optional.
+- **customDetails**: **Object** - Optional.
 - **proposalShape**: **Pattern** - Optional.
 - Returns: **Promise&lt;[Invitation](./zoe-data-types.md#invitation)>**
 
@@ -91,10 +92,12 @@ and returning arbitrary offer results.
 
 **description** is a required string describing the **Invitation**,
 and should include whatever information is needed for a potential recipient of the **Invitation**
-to know what they are getting in the optional **customProperties** argument, which is
-put in the **Invitation**'s **amount**.
-Each one should be a string literal that is unique within its contract and
-used only as the argument to make invitations of a particular kind.
+to distinguish among this contract's invitations.
+Each description should be a string literal that is unique within its contract
+and used only as the argument to make invitations of a particular kind.
+
+The optional **customDetails** argument is included in the **Invitation**'s
+**amount** and not otherwise relied on by Zoe.
 
 ```js
 const creatorInvitation = zcf.makeInvitation(makeCallOption, 'makeCallOption')
@@ -240,7 +243,7 @@ zcf.assertUniqueKeyword(keyword);
 Prohibit invocation of invitatations whose description include any of the strings.
 Any of the strings that end with a colon (`:`) will be treated as a prefix,
 and invitations whose description string begins with the string (including the colon)
-will be burned and not processed if passed to **E(Zoe).offer()**.
+will not be processed if passed to **E(Zoe).offer()**. Instead, an exception will be thrown.
 
 It is expected that most contracts will never invoke this function directly. It is
 intended to be used by **governance** in a legible way, so that the contract's

main/reference/zoe-api/zoe-data-types.md

@@ -40,9 +40,13 @@ An **Invitation Payment** is a **[Payment](/reference/ertp-api/payment.md)** hol
 
 ## InvitationIssuer
 
-The **InvitationIssuer** is a special type of **[Issuer](/reference/ertp-api/issuer.md)**.
-Zoe has a single **InvitationIssuer** for its entire lifetime. All **Invitations** come from the
-**[Mint](/reference/ertp-api/mint.md)** associated with the Zoe instance's **InvitationIssuer**.
+The **InvitationIssuer** is an **[Issuer](/reference/ertp-api/issuer.md)** that plays a
+special role throughout Zoe. Zoe has a single **InvitationIssuer** for its entire
+lifetime. All **Invitations** come from the **[Mint](/reference/ertp-api/mint.md)**
+associated with the Zoe instance's **InvitationIssuer**.
+
+The issuer is publicly available (via [`E(Zoe).getInvitationIssuer()`](./zoe-contract-facet.md#zcf-getinvitationissuer)),
+so the ability to validate invitations is widely available.
 
 **InvitationIssuer** has all the methods of regular **Issuers**, but the two methods that are most
 often used are **[anIssuer.claim()](/reference/ertp-api/issuer.md#anissuer-claim-payment-optamount)**

main/reference/zoe-api/zoe.md

@@ -301,7 +301,7 @@ Used to make an offer to the contract that created the **invitation**.
 
 **proposal** must be either `undefined` or a record with **give**, **want**, and/or **exit** properties
 respectively expressing conditions regarding what is being given,
-what is expected in exchange (protected by offer safety), and
+what is desired in exchange (protected by offer safety), and
 an exit rule defining how/when the offer can be canceled.
 Note that the contract is not obligated to accept the proposal;
 it may inspect it and reject it for any reason
@@ -332,7 +332,7 @@ the Keywords might be "Asset" and "Bid".
 
 **paymentPKeywordRecord** must be either `undefined` or a **[PaymentPKeywordRecord](./zoe-data-types.md#keywordrecord)**
 containing the actual **payments** to be escrowed by Zoe.
-Every **Keyword** in **give** must also have a corresponding **payment**.
+Every **Keyword** in **give** must have a corresponding **payment**.
 
 ```js
 const paymentKeywordRecord = harden({ Asset: quatloosPayment });
@@ -343,7 +343,7 @@ const paymentKeywordRecord = harden({ Asset: quatloosPayment });
 
 **offerArgs** is an optional CopyRecord that can be used to pass additional arguments to the
 **offerHandler** contract code associated with the invitation by
-[`zcf.makeInvitation(...)`](./zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customproperties-proposalshape).
+[`zcf.makeInvitation(...)`](./zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape).
 Each contract can define the properties it supports and which are required.
 
 ## E(Zoe).installBundleID(bundleId)