diff --git a/assignment-client/src/entities/EntityTreeHeadlessViewer.h b/assignment-client/src/entities/EntityTreeHeadlessViewer.h index f4d5911821..a8503510e0 100644 --- a/assignment-client/src/entities/EntityTreeHeadlessViewer.h +++ b/assignment-client/src/entities/EntityTreeHeadlessViewer.h @@ -24,6 +24,9 @@ class EntitySimulation; /**jsdoc + * The EntityViewer API provides a headless viewer for assignment client scripts, so that they can "see" entities + * in order for them to be available in the {@link Entities} API. + * * @namespace EntityViewer * * @hifi-assignment-client diff --git a/assignment-client/src/octree/OctreeHeadlessViewer.h b/assignment-client/src/octree/OctreeHeadlessViewer.h index 67a81b1d2a..2debf2cb84 100644 --- a/assignment-client/src/octree/OctreeHeadlessViewer.h +++ b/assignment-client/src/octree/OctreeHeadlessViewer.h @@ -28,6 +28,7 @@ public: public slots: /**jsdoc + * Updates the entities currently in view. * @function EntityViewer.queryOctree */ void queryOctree(); @@ -36,26 +37,30 @@ public slots: // setters for camera attributes /**jsdoc + * Sets the position of the view frustum. * @function EntityViewer.setPosition - * @param {Vec3} position + * @param {Vec3} position - The position of the view frustum. */ void setPosition(const glm::vec3& position) { _hasViewFrustum = true; _viewFrustum.setPosition(position); } /**jsdoc + * Sets the orientation of the view frustum. * @function EntityViewer.setOrientation - * @param {Quat} orientation + * @param {Quat} orientation - The orientation of the view frustum. */ void setOrientation(const glm::quat& orientation) { _hasViewFrustum = true; _viewFrustum.setOrientation(orientation); } /**jsdoc + * Sets the radius of the center "keyhole" in the view frustum. * @function EntityViewer.setCenterRadius - * @param {number} radius + * @param {number} radius - The radius of the center "keyhole" in the view frustum. */ void setCenterRadius(float radius) { _hasViewFrustum = true; _viewFrustum.setCenterRadius(radius); } /**jsdoc + * Sets the radius of the center "keyhole" in the view frustum. * @function EntityViewer.setKeyholeRadius - * @param {number} radius + * @param {number} radius - The radius of the center "keyhole" in the view frustum. * @deprecated This function is deprecated and will be removed. Use {@link EntityViewer.setCenterRadius|setCenterRadius} * instead. */ @@ -66,33 +71,38 @@ public slots: /**jsdoc * @function EntityViewer.setVoxelSizeScale - * @param {number} sizeScale + * @param {number} sizeScale - The voxel size scale. + * @deprecated This function is deprecated and will be removed. */ void setVoxelSizeScale(float sizeScale) { _octreeQuery.setOctreeSizeScale(sizeScale) ; } /**jsdoc * @function EntityViewer.setBoundaryLevelAdjust - * @param {number} boundaryLevelAdjust + * @param {number} boundaryLevelAdjust - The boundary level adjust factor. + * @deprecated This function is deprecated and will be removed. */ void setBoundaryLevelAdjust(int boundaryLevelAdjust) { _octreeQuery.setBoundaryLevelAdjust(boundaryLevelAdjust); } /**jsdoc + * Sets the maximum number of entity packets to receive from the domain server per second. * @function EntityViewer.setMaxPacketsPerSecond - * @param {number} maxPacketsPerSecond + * @param {number} maxPacketsPerSecond - The maximum number of entity packets to receive per second. */ void setMaxPacketsPerSecond(int maxPacketsPerSecond) { _octreeQuery.setMaxQueryPacketsPerSecond(maxPacketsPerSecond); } // getters for camera attributes /**jsdoc + * Gets the position of the view frustum. * @function EntityViewer.getPosition - * @returns {Vec3} + * @returns {Vec3} The position of the view frustum. */ const glm::vec3& getPosition() const { return _viewFrustum.getPosition(); } /**jsdoc + * Gets the orientation of the view frustum. * @function EntityViewer.getOrientation - * @returns {Quat} + * @returns {Quat} The orientation of the view frustum. */ const glm::quat& getOrientation() const { return _viewFrustum.getOrientation(); } @@ -101,26 +111,30 @@ public slots: /**jsdoc * @function EntityViewer.getVoxelSizeScale - * @returns {number} + * @returns {number} The voxel size scale. + * @deprecated This function is deprecated and will be removed. */ float getVoxelSizeScale() const { return _octreeQuery.getOctreeSizeScale(); } /**jsdoc * @function EntityViewer.getBoundaryLevelAdjust - * @returns {number} + * @returns {number} The boundary level adjust factor. + * @deprecated This function is deprecated and will be removed. */ int getBoundaryLevelAdjust() const { return _octreeQuery.getBoundaryLevelAdjust(); } /**jsdoc + * Gets the maximum number of entity packets to receive from the domain server per second. * @function EntityViewer.getMaxPacketsPerSecond - * @returns {number} + * @returns {number} The maximum number of entity packets to receive per second. */ int getMaxPacketsPerSecond() const { return _octreeQuery.getMaxQueryPacketsPerSecond(); } /**jsdoc + * Gets the number of nodes in the octree. * @function EntityViewer.getOctreeElementsCount - * @returns {number} + * @returns {number} The number of nodes in the octree. */ unsigned getOctreeElementsCount() const { return _tree->getOctreeElementsCount(); } diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index 7c3fd2536d..8aba6b787f 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/libraries/entities/src/EntityScriptingInterface.h @@ -106,8 +106,9 @@ public: * "domain" entities, travel to different domains with a user as "avatar" entities, or be visible only to an individual user as * "local" entities (a.k.a. "overlays"). * - *

Note: For Interface scripts, the entities available to scripts are those that Interface has displayed and so knows - * about.

+ *

Note: For Interface, avatar, and client entity scripts, the entities available to scripts are those that Interface has + * displayed and so knows about. For assignment client scripts, the entities available are those that are "seen" by the + * {@link EntityViewer}. For entity server scripts, all entities are available.

* *

Entity Methods

* diff --git a/libraries/plugins/src/plugins/SteamClientPlugin.h b/libraries/plugins/src/plugins/SteamClientPlugin.h index 2124d16b5e..07e320f8eb 100644 --- a/libraries/plugins/src/plugins/SteamClientPlugin.h +++ b/libraries/plugins/src/plugins/SteamClientPlugin.h @@ -41,13 +41,16 @@ public: }; /**jsdoc + * The Steam API provides facilities for working with the Steam version of Interface. + * * @namespace Steam * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {boolean} running - Read-only. + * @property {boolean} running - true if Interface is running under Steam, false if it isn't. + * Read-only. */ class SteamScriptingInterface : public QObject { @@ -61,13 +64,22 @@ public: public slots: /**jsdoc + * Gets whether Interface is running under Steam. * @function Steam.isRunning - * @returns {boolean} + * @returns {boolean} true if Interface is running under Steam, false if it isn't. */ bool isRunning() const { return _plugin && _plugin->isRunning(); } /**jsdoc + * Opens Steam's "Choose Friends to invite" dialog if Interface is running under Steam. * @function Steam.openInviteOverlay + * @example Invite Steam friends to join you in High Fidelity. + * if (Steam.running) { + * print("Invite Steam friends to joint you..."); + * Steam.openInviteOverlay(); + * } else { + * print("Interface isn't running under Steam."); + * } */ void openInviteOverlay() const { if (_plugin) { _plugin->openInviteOverlay(); } } diff --git a/libraries/script-engine/src/FileScriptingInterface.h b/libraries/script-engine/src/FileScriptingInterface.h index 859f343ec5..ce93921403 100644 --- a/libraries/script-engine/src/FileScriptingInterface.h +++ b/libraries/script-engine/src/FileScriptingInterface.h @@ -17,6 +17,8 @@ #include /**jsdoc + * The File API provides some facilities for working with the file system. + * * @namespace File * * @hifi-interface @@ -35,37 +37,69 @@ public: public slots: /**jsdoc + * Extracts a filename from a URL, where the filename is specified in the query part of the URL as filename=. * @function File.convertUrlToPath - * @param {string} url - * @returns {string} + * @param {string} url - The URL to extract the filename from. + * @returns {string} The filename specified in the URL; an empty string if no filename is specified. + * @example Extract a filename from a URL. + * var url = "http://domain.tld/path/page.html?filename=file.ext"; + * print("File name: " + File.convertUrlToPath(url)); // file.ext */ QString convertUrlToPath(QUrl url); /**jsdoc + * Unzips a file in the local file system to a new, unique temporary directory. * @function File.runUnzip - * @param {string} path - * @param {string} url - * @param {boolean} autoAdd - * @param {boolean} isZip - * @param {boolean} isBlocks + * @param {string} path - The path of the zip file in the local file system. May have a leading "file:///". + * Need not have a ".zip" extension if it is in a temporary directory (as created by + * {@link File.getTempDir|getTempDir}). + * @param {string} url - Not used. + * @param {boolean} autoAdd - Not used by user scripts. The value is simply passed through to the + * {@link File.unzipResult|unzipResult} signal. + * @param {boolean} isZip - Set to true if path has a ".zip" extension, + * false if it doesn't (but should still be treated as a zip file). + * @param {boolean} isBlocks - Not used by user scripts. The value is simply passed through to the + * {@link File.unzipResult|unzipResult} signal. + * @example Select and unzip a file. + * File.unzipResult.connect(function (zipFile, unzipFiles, autoAdd, isZip, isBlocks) { + * print("File.unzipResult()"); + * print("- zipFile: " + zipFile); + * print("- unzipFiles(" + unzipFiles.length + "): " + unzipFiles); + * print("- autoAdd: " + autoAdd); + * print("- isZip: " + isZip); + * print("- isBlocks: " + isBlocks); + * }); + * + * var zipFile = Window.browse("Select a Zip File", "", "*.zip"); + * if (zipFile) { + * File.runUnzip(zipFile, "", false, true, false); + * } else { + * print("Zip file not selected."); + * } */ void runUnzip(QString path, QUrl url, bool autoAdd, bool isZip, bool isBlocks); /**jsdoc + * Creates a new, unique directory for temporary use. * @function File.getTempDir - * @returns {string} + * @returns {string} The path of the newly created temporary directory. + * @example Create a temporary directory. + * print("New temporary directory: " + File.getTempDir()); */ QString getTempDir(); signals: /**jsdoc + * Triggered when {@link File.runUnzip|runUnzip} completes. * @function File.unzipResult - * @param {string} zipFile - * @param {string} unzipFile - * @param {boolean} autoAdd - * @param {boolean} isZip - * @param {boolean} isBlocks + * @param {string} zipFile - The file that was unzipped. + * @param {string[]} unzipFiles - The paths of the unzipped files in a newly created temporary directory. Includes entries + * for any subdirectories created. An empty array if the zipFile could not be unzipped. + * @param {boolean} autoAdd - The value that {@link File.runUnzip|runUnzip} was called with. + * @param {boolean} isZip - true if {@link File.runUnzip|runUnzip} was called with isZip == true, + * unless there is no FBX or OBJ file in the unzipped file(s) in which case the value is false. + * @param {boolean} isBlocks - The value that {@link File.runUnzip|runUnzip} was called with. * @returns {Signal} */ void unzipResult(QString zipFile, QStringList unzipFile, bool autoAdd, bool isZip, bool isBlocks);