From 2a338124aec750340617bbbff8766a224d2d61c1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 15 Feb 2019 08:00:19 +1300 Subject: [PATCH] AccountServices API JSDoc --- .../AccountServicesScriptingInterface.cpp | 6 ++ .../AccountServicesScriptingInterface.h | 75 +++++++++++++++---- 2 files changed, 68 insertions(+), 13 deletions(-) diff --git a/interface/src/scripting/AccountServicesScriptingInterface.cpp b/interface/src/scripting/AccountServicesScriptingInterface.cpp index 3939fce91d..a3597886e9 100644 --- a/interface/src/scripting/AccountServicesScriptingInterface.cpp +++ b/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(); diff --git a/interface/src/scripting/AccountServicesScriptingInterface.h b/interface/src/scripting/AccountServicesScriptingInterface.h index fb3c329def..2234583641 100644 --- a/interface/src/scripting/AccountServicesScriptingInterface.h +++ b/interface/src/scripting/AccountServicesScriptingInterface.h @@ -38,16 +38,24 @@ class AccountServicesScriptingInterface : public QObject { Q_OBJECT /**jsdoc - * The AccountServices API contains helper functions related to user connectivity + * The AccountServices API provides functions related to user connectivity, visibility, and asset download + * progress. * * @hifi-interface * @hifi-client-entity * * @namespace AccountServices - * @property {string} username Read-only. - * @property {boolean} loggedIn Read-only. - * @property {string} findableBy - * @property {string} metaverseServerURL Read-only. + * @property {string} username - The user name if the user is logged in, otherwise "Unknown user". + * Read-only. + * @property {boolean} loggedIn - true if the user is logged in, otherwise false. + * Read-only. + * @property {string} findableBy - The user's visibility to other people:
+ * "none" - user appears offline.
+ * "friends" - user is visible only to friends.
+ * "connections" - user is visible to friends and connections.
+ * "all" - user is visible to everyone. + * @property {string} metaverseServerURL - The metaverse server that the user is authenticated against when logged in + * — typically "https://metaverse.highfidelity.com". Read-only. */ Q_PROPERTY(QString username READ getUsername NOTIFY myUsernameChanged) @@ -65,29 +73,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} true if the user is logged in, false otherwise. + * @example Report whether you are logged in. + * 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} true if the user is already logged in, false otherwise. */ bool checkAndSignalForAccessToken(); /**jsdoc + * Logs the user out. * @function AccountServices.logOut */ void logOut(); @@ -105,43 +122,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, "logout". * @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 "". * @returns {Signal} + * @example Report when your username changes. + * 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:
+ * "none" - user appears offline.
+ * "friends" - user is visible only to friends.
+ * "connections" - user is visible to friends and connections.
+ * "all" - user is visible to everyone. * @returns {Signal} + * @example Report when your visiblity changes. + * 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 - true if the user is logged in, otherwise false. * @returns {Signal} + * @example Report when your login status changes. + * AccountServices.loggedInChanged.connect(function(loggedIn) { + * print("Logged in: " + loggedIn); + * }); */ void loggedInChanged(bool loggedIn);