WalletScriptingInterface API JSDoc

interface/src/commerce/Wallet.h

@@ -54,6 +54,29 @@ public:
     void clear();
 
     void getWalletStatus();
+    
+    /**jsdoc
+     * <p>A <code>WalletStatus</code> may have one of the following values:</p>
+     * <table>
+     *   <thead>
+     *     <tr><th>Value</th><th>Meaning</th><th>Description</th></tr>
+     *   </thead>
+     *   <tbody>
+     *     <tr><td><code>0</code></td><td>Not logged in</td><td>The user isn't logged in.</td></tr>
+     *     <tr><td><code>1</code></td><td>Not set up</td><td>The user's wallet isn't set up.</td></tr>
+     *     <tr><td><code>2</code></td><td>Pre-existing</td><td>There is a wallet present on the server but not one 
+     *       locally.</td></tr>
+     *     <tr><td><code>3</code></td><td>Conflicting</td><td>There is a wallet present on the server plus one present locally, 
+     *       and they don't match.</td></tr>
+     *     <tr><td><code>4</code></td><td>Not authenticated</td><td>There is a wallet present locally but the user hasn't 
+     *       logged into it.</td></tr>
+     *     <tr><td><code>5</code></td><td>Ready</td><td>The wallet is ready for use.</td></tr>
+     *   </tbody>
+     * </table>
+     * <p>Wallets used to be stored locally but now they're stored on the server, unless the computer once had a wallet stored
+     * locally in which case the wallet may be present in both places.</p>
+     * @typedef {number} WalletScriptingInterface.WalletStatus
+     */
     enum WalletStatus {
         WALLET_STATUS_NOT_LOGGED_IN = 0,
         WALLET_STATUS_NOT_SET_UP,

interface/src/scripting/WalletScriptingInterface.h

@@ -1,4 +1,4 @@
-
+//
 //  WalletScriptingInterface.h
 //  interface/src/scripting
 //
@@ -30,13 +30,18 @@ public:
 };
 
 /**jsdoc
- * @namespace Wallet
+ * The <code>WalletScriptingInterface</code> API provides functions related to the user's wallet and verification of certified 
+ * avatar entities.
+ *
+ * @namespace WalletScriptingInterface
  *
  * @hifi-interface
  * @hifi-client-entity
  *
- * @property {number} walletStatus
- * @property {bool} limitedCommerce
+ * @property {WalletScriptingInterface.WalletStatus} walletStatus - The status of the user's wallet. <em>Read-only.</em>
+ * @property {boolean} limitedCommerce - <code>true</code> if Interface is running in limited commerce mode. In limited commerce 
+ *     mode, certain Interface functionality is disabled, e.g., users can't buy non-free items from the Marketplace. The Oculus 
+ *     Store version of Interface runs in limited commerce mode. <em>Read-only.</em>
  */
 class WalletScriptingInterface : public QObject, public Dependency {
     Q_OBJECT
@@ -49,19 +54,56 @@ public:
     WalletScriptingInterface();
 
     /**jsdoc
+     * Check and update the user's wallet status.
      * @function WalletScriptingInterface.refreshWalletStatus
      */
     Q_INVOKABLE void refreshWalletStatus();
 
     /**jsdoc
+     * Get the current status of the user's wallet.
      * @function WalletScriptingInterface.getWalletStatus
-     * @returns {number}
+     * @returns {WalletScriptingInterface.WalletStatus}
+     * @example <caption>Two ways to report your wallet status.</caption>
+     * print("Wallet status: " + WalletScriptingInterface.walletStatus);  // Same value as next line.
+     * print("Wallet status: " + WalletScriptingInterface.getWalletStatus());
      */
     Q_INVOKABLE uint getWalletStatus() { return _walletStatus; }
 
     /**jsdoc
+     * Check that a certified avatar entity is owned by the avatar whose entity it is. The result of the check is provided via 
+     * the {@link WalletScriptingInterface.ownershipVerificationSuccess|ownershipVerificationSuccess} and 
+     * {@link WalletScriptingInterface.ownershipVerificationFailed|ownershipVerificationFailed} signals.<br />
+     * <strong>Warning:</strong> Neither of these signals fire if the entity is not an avatar entity or it's not a certified 
+     * entity.
      * @function WalletScriptingInterface.proveAvatarEntityOwnershipVerification
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the avatar entity to check.
+     * @example <caption>Check ownership of all nearby certified avatar entities.</caption>
+     * // Set up response handling.
+     * function ownershipSuccess(entityID) {
+     *     print("Ownership test succeeded for: " + entityID);
+     * }
+     * function ownershipFailed(entityID) {
+     *     print("Ownership test failed for: " + entityID);
+     * }
+     * WalletScriptingInterface.ownershipVerificationSuccess.connect(ownershipSuccess);
+     * WalletScriptingInterface.ownershipVerificationFailed.connect(ownershipFailed);
+     * 
+     * // Check ownership of all nearby certified avatar entities.
+     * var entityIDs = Entities.findEntities(MyAvatar.position, 10);
+     * var i, length;
+     * for (i = 0, length = entityIDs.length; i < length; i++) {
+     *     var properties = Entities.getEntityProperties(entityIDs[i], ["entityHostType", "certificateID"]);
+     *     if (properties.entityHostType === "avatar" && properties.certificateID !== "") {
+     *         print("Prove ownership of: " + entityIDs[i]);
+     *         WalletScriptingInterface.proveAvatarEntityOwnershipVerification(entityIDs[i]);
+     *     }
+     * }
+     * 
+     * // Tidy up.
+     * Script.scriptEnding.connect(function () {
+     *     WalletScriptingInterface.ownershipVerificationFailed.disconnect(ownershipFailed);
+     *     WalletScriptingInterface.ownershipVerificationSuccess.disconnect(ownershipSuccess);
+     * });
      */
     Q_INVOKABLE void proveAvatarEntityOwnershipVerification(const QUuid& entityID);
 
@@ -75,33 +117,45 @@ public:
 signals:
 
     /**jsdoc
+     * Triggered when the status of the user's wallet changes.
      * @function WalletScriptingInterface.walletStatusChanged
      * @returns {Signal}
+     * @example <caption>Report when your wallet status changes, e.g., when you log in and out.</caption>
+     * WalletScriptingInterface.walletStatusChanged.connect(function () {
+     *     print("Wallet status changed to: " + WalletScriptingInterface.walletStatus");
+     * });
      */
     void walletStatusChanged();
 
     /**jsdoc
+     * Triggered when the user's limited commerce status changes.
      * @function WalletScriptingInterface.limitedCommerceChanged
      * @returns {Signal}
      */
     void limitedCommerceChanged();
 
     /**jsdoc
+     * Triggered when the user rezzes a certified entity but the user's wallet is not ready and so the certified location of the 
+     * entity cannot be updated in the metaverse.
      * @function WalletScriptingInterface.walletNotSetup
      * @returns {Signal}
      */
     void walletNotSetup();
 
     /**jsdoc
+     * Triggered when a certified avatar entity's ownership check requested via 
+     * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} succeeds. 
      * @function WalletScriptingInterface.ownershipVerificationSuccess
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the avatar entity checked.
      * @returns {Signal}
      */
     void ownershipVerificationSuccess(const QUuid& entityID);
 
     /**jsdoc
+     * Triggered when a certified avatar entity's ownership check requested via
+     * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} fails.
      * @function WalletScriptingInterface.ownershipVerificationFailed
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the avatar entity checked.
      * @returns {Signal}
      */
     void ownershipVerificationFailed(const QUuid& entityID);