From 4fb55ec2afffe000472296d56dfb8522c142f6f3 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Apr 2018 09:59:14 +1200 Subject: [PATCH] Interim JSDoc for Users --- .../src/UsersScriptingInterface.h | 157 +++++++++++------- 1 file changed, 93 insertions(+), 64 deletions(-) diff --git a/libraries/script-engine/src/UsersScriptingInterface.h b/libraries/script-engine/src/UsersScriptingInterface.h index a4e741a797..6728c471f6 100644 --- a/libraries/script-engine/src/UsersScriptingInterface.h +++ b/libraries/script-engine/src/UsersScriptingInterface.h @@ -17,8 +17,12 @@ #include /**jsdoc -* @namespace Users -*/ + * @namespace Users + * @property {boolean} canKick - true if the domain server allows the node or avatar to kick (ban) avatars, + * otherwise false. Read-only. + * @property {boolean} requestsDomainListData - true if the avatar requests extra data from the mixers (such as + * positional data of an avatar you've ignored). Read-only. + */ class UsersScriptingInterface : public QObject, public Dependency { Q_OBJECT SINGLETON_DEPENDENCY @@ -32,126 +36,151 @@ public: public slots: /**jsdoc - * Ignore another user. - * @function Users.ignore - * @param {nodeID} nodeID The node or session ID of the user you want to ignore. - * @param {bool} enable True for ignored; false for un-ignored. - */ + * Personally ignore another user, making them disappear for you and you disappear for them. + * @function Users.ignore + * @param {Uuid} nodeID The node or session ID of the user you want to ignore. + * @param {boolean} enable True for ignored; false for un-ignored. + */ void ignore(const QUuid& nodeID, bool ignoreEnabled = true); /**jsdoc - * Gets a bool containing whether you have ignored the given Avatar UUID. - * @function Users.getIgnoreStatus - * @param {nodeID} nodeID The node or session ID of the user whose ignore status you want. - */ + * Get whether or not you have ignored the node with the given UUID. + * @function Users.getIgnoreStatus + * @param {Uuid} nodeID The node or session ID of the user whose ignore status you want. + * @returns {boolean} + */ bool getIgnoreStatus(const QUuid& nodeID); /**jsdoc - * Mute another user for you and you only. - * @function Users.personalMute - * @param {nodeID} nodeID The node or session ID of the user you want to mute. - * @param {bool} enable True for enabled; false for disabled. - */ + * Mute another user for you and you only. They won't be able to hear you, and you won't be able to hear them. + * @function Users.personalMute + * @param {Uuid} nodeID The node or session ID of the user you want to mute. + * @param {boolean} muteEnabled True for enabled; false for disabled. + */ void personalMute(const QUuid& nodeID, bool muteEnabled = true); /**jsdoc - * Requests a bool containing whether you have personally muted the given Avatar UUID. - * @function Users.requestPersonalMuteStatus - * @param {nodeID} nodeID The node or session ID of the user whose personal mute status you want. - */ + * Get whether or not you have personally muted the node with the given UUID. + * @function Users.requestPersonalMuteStatus + * @param {Uuid} nodeID The node or session ID of the user whose personal mute status you want. + * @returns {boolean} + */ bool getPersonalMuteStatus(const QUuid& nodeID); /**jsdoc - * Sets an avatar's gain for you and you only. - * Units are Decibels (dB) - * @function Users.setAvatarGain - * @param {nodeID} nodeID The node or session ID of the user whose gain you want to modify, or null to set the master gain. - * @param {float} gain The gain of the avatar you'd like to set. Units are dB. + * Sets an avatar's gain for you and you only. + * Units are Decibels (dB) + * @function Users.setAvatarGain + * @param {Uuid} nodeID The node or session ID of the user whose gain you want to modify, or null to set the master gain. + * @param {number} gain The gain of the avatar you'd like to set. Units are dB. */ void setAvatarGain(const QUuid& nodeID, float gain); /**jsdoc - * Gets an avatar's gain for you and you only. - * @function Users.getAvatarGain - * @param {nodeID} nodeID The node or session ID of the user whose gain you want to get, or null to get the master gain. - * @return {float} gain (in dB) + * Gets an avatar's gain for you and you only. + * @function Users.getAvatarGain + * @param {Uuid} nodeID The node or session ID of the user whose gain you want to get, or null to get the master gain. + * @returns {number} gain (in dB) */ float getAvatarGain(const QUuid& nodeID); /**jsdoc - * Kick another user. - * @function Users.kick - * @param {nodeID} nodeID The node or session ID of the user you want to kick. - */ + * Kick/ban another user. Removes them from the server and prevents them from returning. Bans by either user name (if + * available) or machine fingerprint otherwise. This will only do anything if you're an admin of the domain you're in. + * @function Users.kick + * @param {Uuid} nodeID The node or session ID of the user you want to kick. + */ void kick(const QUuid& nodeID); /**jsdoc - * Mute another user for everyone. - * @function Users.mute - * @param {nodeID} nodeID The node or session ID of the user you want to mute. - */ + * Mutes another user's microphone for everyone. Not permanent; the silenced user can unmute themselves with the UNMUTE + * button in their HUD. This will only do anything if you're an admin of the domain you're in. + * @function Users.mute + * @param {Uuid} nodeID The node or session ID of the user you want to mute. + */ void mute(const QUuid& nodeID); /**jsdoc - * Returns a string containing the username associated with the given Avatar UUID + * Get the user name and machine fingerprint associated with the given UUID. This will only do anything if you're an admin + * of the domain you're in. * @function Users.getUsernameFromID - * @param {nodeID} nodeID The node or session ID of the user whose username you want. + * @param {Uuid} nodeID The node or session ID of the user whose username you want. */ void requestUsernameFromID(const QUuid& nodeID); /**jsdoc - * Returns `true` if the DomainServer will allow this Node/Avatar to make kick - * @function Users.getCanKick - * @return {bool} `true` if the client can kick other users, `false` if not. - */ + * Returns `true` if the DomainServer will allow this Node/Avatar to make kick. + * @function Users.getCanKick + * @returns {boolean} true if the domain server allows the client to kick (ban) other users, otherwise + * false. + */ bool getCanKick(); /**jsdoc - * Toggle the state of the ignore in radius feature - * @function Users.toggleIgnoreRadius - */ + * Toggle the state of the space bubble feature. + * @function Users.toggleIgnoreRadius + */ void toggleIgnoreRadius(); /**jsdoc - * Enables the ignore radius feature. - * @function Users.enableIgnoreRadius - */ + * Enables the space bubble feature. + * @function Users.enableIgnoreRadius + */ void enableIgnoreRadius(); /**jsdoc - * Disables the ignore radius feature. - * @function Users.disableIgnoreRadius - */ + * Disables the space bubble feature. + * @function Users.disableIgnoreRadius + */ void disableIgnoreRadius(); /**jsdoc - * Returns `true` if the ignore in radius feature is enabled - * @function Users.getIgnoreRadiusEnabled - * @return {bool} `true` if the ignore in radius feature is enabled, `false` if not. - */ + * Returns `true` if the space bubble feature is enabled. + * @function Users.getIgnoreRadiusEnabled + * @returns {boolean} true if the space bubble is enabled, otherwise false. + */ bool getIgnoreRadiusEnabled(); signals: + + /**jsdoc + * @function Users.canKickChanged + * @param {boolean} canKick + * @returns {Signal} + */ void canKickChanged(bool canKick); + + /**jsdoc + * @function Users.ignoreRadiusEnabledChanged + * @param {boolean} isEnabled + * @returns {Signal} + */ void ignoreRadiusEnabledChanged(bool isEnabled); /**jsdoc - * Notifies scripts that another user has entered the ignore radius - * @function Users.enteredIgnoreRadius - */ + * Notifies scripts that another user has entered the ignore radius. + * @function Users.enteredIgnoreRadius + * @returns {Signal} + */ void enteredIgnoreRadius(); /**jsdoc - * Notifies scripts of the username and machine fingerprint associated with a UUID. - * Username and machineFingerprint will be their default constructor output if the requesting user isn't an admin. - * @function Users.usernameFromIDReply + * Notifies scripts of the user name and machine fingerprint associated with a UUID. + * Username and machineFingerprint will be their default constructor output if the requesting user isn't an admin. + * @function Users.usernameFromIDReply + * @param {Uuid} nodeID + * @param {string} userName + * @param {string} machineFingerprint + * @param {boolean} isAdmin + * @returns {Signal} */ void usernameFromIDReply(const QString& nodeID, const QString& username, const QString& machineFingerprint, bool isAdmin); /**jsdoc - * Notifies scripts that a user has disconnected from the domain + * Notifies scripts that a user has disconnected from the domain. * @function Users.avatarDisconnected - * @param {nodeID} NodeID The session ID of the avatar that has disconnected + * @param {Uuid} nodeID The session ID of the avatar that has disconnected. + * @returns {Signal} */ void avatarDisconnected(const QUuid& nodeID);