Merge pull request #14918 from ctrlaltdavid/M21128

Case 21128: AccountServices, HifiAbout, and WalletScriptingInterface JSDoc

interface/src/AboutUtil.h

@@ -16,15 +16,23 @@
 #include <QObject>
 
 /**jsdoc
+ * The <code>HifiAbout</code> API provides information about the version of Interface that is currently running. It also 
+ * provides the ability to open a Web page in an Interface browser window.
+ *
  * @namespace HifiAbout
  *
  * @hifi-interface
  * @hifi-client-entity
  * @hifi-avatar
  *
- * @property {string} buildDate
+ * @property {string} buildDate - The build date of Interface that is currently running. <em>Read-only.</em>
- * @property {string} buildVersion
+ * @property {string} buildVersion - The build version of Interface that is currently running. <em>Read-only.</em>
- * @property {string} qtVersion
+ * @property {string} qtVersion - The Qt version used in Interface that is currently running. <em>Read-only.</em>
+ *
+ * @example <caption>Report build information for the version of Interface currently running.</caption>
+ * print("HiFi build date: " + HifiAbout.buildDate);  // 11 Feb 2019
+ * print("HiFi version: " + HifiAbout.buildVersion);  // 0.78.0
+ * print("Qt version: " + HifiAbout.qtVersion);  // 5.10.1
  */
 
 class AboutUtil : public QObject {
@@ -44,8 +52,9 @@ public:
 public slots:
 
     /**jsdoc
+     * Display a Web page in an Interface browser window.
      * @function HifiAbout.openUrl
-     * @param {string} url
+     * @param {string} url - The URL of the Web page to display.
      */
     void openUrl(const QString &url) const;
 private:

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/AccountServicesScriptingInterface.cpp

@@ -112,6 +112,12 @@ DownloadInfoResult::DownloadInfoResult() :
 {
 }
 
+/**jsdoc
+ * Information on the assets currently being downloaded and pending download.
+ * @typedef {object} AccountServices.DownloadInfoResult
+ * @property {number[]} downloading - The percentage complete for each asset currently being downloaded.
+ * @property {number} pending - The number of assets waiting to be download.
+ */
 QScriptValue DownloadInfoResultToScriptValue(QScriptEngine* engine, const DownloadInfoResult& result) {
     QScriptValue object = engine->newObject();
 

interface/src/scripting/AccountServicesScriptingInterface.h

@@ -38,17 +38,25 @@ class AccountServicesScriptingInterface : public QObject {
     Q_OBJECT
 
     /**jsdoc
-     * The AccountServices API contains helper functions related to user connectivity
+     * The <code>AccountServices</code> API provides functions related to user connectivity, visibility, and asset download 
+     * progress.
      * 
      * @hifi-interface
      * @hifi-client-entity
      * @hifi-avatar
      *
      * @namespace AccountServices
-     * @property {string} username <em>Read-only.</em>
+     * @property {string} username - The user name if the user is logged in, otherwise <code>"Unknown user"</code>.
-     * @property {boolean} loggedIn <em>Read-only.</em>
+     *     <em>Read-only.</em>
-     * @property {string} findableBy
+     * @property {boolean} loggedIn - <code>true</code> if the user is logged in, otherwise <code>false</code>. 
-     * @property {string} metaverseServerURL <em>Read-only.</em>
+     *     <em>Read-only.</em>
+     * @property {string} findableBy - The user's visibility to other people:<br />
+     *     <code>"none"</code> - user appears offline.<br />
+     *     <code>"friends"</code> - user is visible only to friends.<br />
+     *     <code>"connections"</code> - user is visible to friends and connections.<br />
+     *     <code>"all"</code> - user is visible to everyone.
+     * @property {string} metaverseServerURL - The metaverse server that the user is authenticated against when logged in 
+     *     &mdash; typically <code>"https://metaverse.highfidelity.com"</code>. <em>Read-only.</em>
      */
 
     Q_PROPERTY(QString username READ getUsername NOTIFY myUsernameChanged)
@@ -66,29 +74,38 @@ public:
 public slots:
 
     /**jsdoc
+     * Get information on the progress of downloading assets in the domain.
      * @function AccountServices.getDownloadInfo
-     * @returns {DownloadInfoResult}
+     * @returns {AccountServices.DownloadInfoResult} Information on the progress of assets download.
      */
     DownloadInfoResult getDownloadInfo();
 
     /**jsdoc
+     * Cause a {@link AccountServices.downloadInfoChanged|downloadInfoChanged} signal to be triggered with information on the 
+     * current progress of the download of assets in the domain.
      * @function AccountServices.updateDownloadInfo
      */
     void updateDownloadInfo();
 
     /**jsdoc
+     * Check whether the user is logged in.
      * @function AccountServices.isLoggedIn
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the user is logged in, <code>false</code> otherwise.
+     * @example <caption>Report whether you are logged in.</caption>
+     * var isLoggedIn = AccountServices.isLoggedIn();
+     * print("You are logged in: " + isLoggedIn);  // true or false
      */
     bool isLoggedIn();
 
     /**jsdoc
+     * Prompts the user to log in (the login dialog is displayed) if they're not already logged in.
      * @function AccountServices.checkAndSignalForAccessToken
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the user is already logged in, <code>false</code> otherwise.
      */
     bool checkAndSignalForAccessToken();
 
     /**jsdoc
+     * Logs the user out.
      * @function AccountServices.logOut
      */
     void logOut();
@@ -106,43 +123,75 @@ private slots:
 signals:
 
     /**jsdoc
+     * Not currently used.
      * @function AccountServices.connected
      * @returns {Signal}
      */
     void connected();
 
     /**jsdoc
+     * Triggered when the user logs out.
      * @function AccountServices.disconnected
-     * @param {string} reason
+     * @param {string} reason - Has the value, <code>"logout"</code>.
      * @returns {Signal}
      */
     void disconnected(const QString& reason);
 
     /**jsdoc
+     * Triggered when the username logged in with changes, i.e., when the user logs in or out.
      * @function AccountServices.myUsernameChanged
-     * @param {string} username
+     * @param {string} username - The username logged in with if the user is logged in, otherwise <code>""</code>.
      * @returns {Signal}
+     * @example <caption>Report when your username changes.</caption>
+     * AccountServices.myUsernameChanged.connect(function (username) {
+     *     print("Username changed: " + username);
+     * });
      */
     void myUsernameChanged(const QString& username);
 
     /**jsdoc
+     * Triggered when the progress of the download of assets for the domain changes.
      * @function AccountServices.downloadInfoChanged
-     * @param {} info
+     * @param {AccountServices.DownloadInfoResult} downloadInfo - Information on the progress of assets download.
      * @returns {Signal}
      */
     void downloadInfoChanged(DownloadInfoResult info);
 
     /**jsdoc
+     * Triggered when the user's visibility to others changes.
      * @function AccountServices.findableByChanged
-     * @param {string} discoverabilityMode
+     * @param {string} findableBy - The user's visibility to other people:<br />
+     *     <code>"none"</code> - user appears offline.<br />
+     *     <code>"friends"</code> - user is visible only to friends.<br />
+     *     <code>"connections"</code> - user is visible to friends and connections.<br />
+     *     <code>"all"</code> - user is visible to everyone.
      * @returns {Signal}
+     * @example <caption>Report when your visiblity changes.</caption>
+     * AccountServices.findableByChanged.connect(function (findableBy) {
+     *     print("Findable by changed: " + findableBy);
+     * });
+     * 
+     * var originalFindableBy = AccountServices.findableBy;
+     * Script.setTimeout(function () {
+     *     // Change visiblity.
+     *     AccountServices.findableBy = originalFindableBy === "none" ? "all" : "none";
+     * }, 2000);
+     * Script.setTimeout(function () {
+     *     // Restore original visibility.
+     *     AccountServices.findableBy = originalFindableBy;
+     * }, 4000);
      */
     void findableByChanged(const QString& discoverabilityMode);
 
     /**jsdoc
+     * Triggered when the login status of the user changes.
      * @function AccountServices.loggedInChanged
-     * @param {boolean} loggedIn
+     * @param {boolean} loggedIn - <code>true</code> if the user is logged in, otherwise <code>false</code>.
      * @returns {Signal}
+     * @example <caption>Report when your login status changes.</caption>
+     * AccountServices.loggedInChanged.connect(function(loggedIn) {
+     *     print("Logged in: " + loggedIn);
+     * });
      */
     void loggedInChanged(bool loggedIn);
 

interface/src/scripting/WalletScriptingInterface.h

@@ -1,4 +1,4 @@
-
+//
 //  WalletScriptingInterface.h
 //  interface/src/scripting
 //
@@ -30,14 +30,19 @@ 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
  * @hifi-avatar
  *
- * @property {number} walletStatus
+ * @property {WalletScriptingInterface.WalletStatus} walletStatus - The status of the user's wallet. <em>Read-only.</em>
- * @property {bool} limitedCommerce
+ * @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
@@ -50,19 +55,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);
 
@@ -76,33 +118,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);