fixup! review suggestions

packages/zoe/src/contractSupport/prepare-ownable.js

@@ -15,15 +15,25 @@ const TransferProposalShape = M.splitRecord({
  * @typedef {object} OwnableOptions
  * @property {string} [uInterfaceName]
  *   The `interfaceName` of the underlying interface guard.
- *   Defaults to the uKindName
+ *   Defaults to the `uKindName`.
  */
 
 /**
  * @template {any} [U=any]
  * @param {import('@agoric/base-zone').Zone} zone
  * @param {MakeInvitation} makeInvitation
+ *   A function with the same behavior as `zcf.makeInvitation`.
+ *   A contract will normally just extract it from its own zcf using the
+ *   argument expression
+ *   ```js
+ *   (...args) => zcf.makeInvitation(...args)
+ *   ```
+ *   See ownable-counter.js for the canonical example.
  * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
  * @param {(string|symbol)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the wrapping ownable object.
  * @param {OwnableOptions} [options]
  * @returns {(underlying: U) => U}
  */

packages/zoe/src/contractSupport/prepare-revocable.js

@@ -21,7 +21,7 @@ const { Fail, quote: q } = assert;
  * @typedef {object} RevocableKitOptions
  * @property {string} [uInterfaceName]
  *   The `interfaceName` of the underlying interface guard.
- *   Defaults to the uKindName
+ *   Defaults to the `uKindName`.
  * @property {Record<
  *   string|symbol,
  *   import('@endo/patterns').MethodGuard
@@ -47,7 +47,7 @@ const { Fail, quote: q } = assert;
  *   The `kindName` of the underlying exo class
  * @param {(string|symbol)[]} uMethodNames
  *   The method names of the underlying exo class that should be represented
- *   by a transparently-forwarding method of the revocable caretaker.
+ *   by transparently-forwarding methods of the revocable caretaker.
  * @param {RevocableKitOptions} [options]
  * @returns {(underlying: U) => RevocableKit<U>}
  */