Merge pull request #15591 from ctrlaltdavid/M22493

Case 22493: Script JSDoc

libraries/entities/src/EntityScriptingInterface.h

@@ -1770,6 +1770,7 @@ signals:
     /**jsdoc
      * Triggered on the client that is the physics simulation owner during the collision of two entities. Note: Isn't triggered 
      * for a collision with an avatar.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.collisionWithEntity
      * @param {Uuid} idA - The ID of one entity in the collision. For an entity script, this is the ID of the entity containing 
      *     the script.
@@ -1882,6 +1883,7 @@ signals:
     /**jsdoc
      * Triggered when a mouse button is clicked while the mouse cursor is on an entity, or a controller trigger is fully 
      * pressed while its laser is on an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.mousePressOnEntity
      * @param {Uuid} entityID - The ID of the entity that was pressed.
      * @param {PointerEvent} event - Details of the event.
@@ -1906,6 +1908,7 @@ signals:
 
     /**jsdoc
      * Repeatedly triggered while the mouse cursor or controller laser moves on an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.mouseMoveOnEntity
      * @param {Uuid} entityID - The ID of the entity that was moved on.
      * @param {PointerEvent} event - Details of the event.
@@ -1916,6 +1919,7 @@ signals:
     /**jsdoc
      * Triggered when a mouse button is released after clicking on an entity or the controller trigger is partly or fully 
      * released after pressing on an entity, even if the mouse pointer or controller laser has moved off the entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.mouseReleaseOnEntity
      * @param {Uuid} entityID - The ID of the entity that was originally pressed.
      * @param {PointerEvent} event - Details of the event.
@@ -1942,6 +1946,7 @@ signals:
 
     /**jsdoc
      * Triggered when a mouse button is clicked while the mouse cursor is on an entity. Note: Not triggered by controller.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.clickDownOnEntity
      * @param {Uuid} entityID - The ID of the entity that was clicked.
      * @param {PointerEvent} event - Details of the event.
@@ -1952,6 +1957,7 @@ signals:
     /**jsdoc
      * Repeatedly triggered while a mouse button continues to be held after clicking an entity, even if the mouse cursor has 
      * moved off the entity. Note: Not triggered by controller.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.holdingClickOnEntity
      * @param {Uuid} entityID - The ID of the entity that was originally clicked.
      * @param {PointerEvent} event - Details of the event.
@@ -1962,6 +1968,7 @@ signals:
     /**jsdoc
      * Triggered when a mouse button is released after clicking on an entity, even if the mouse cursor has moved off the 
      * entity. Note: Not triggered by controller.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.clickReleaseOnEntity
      * @param {Uuid} entityID - The ID of the entity that was originally clicked.
      * @param {PointerEvent} event - Details of the event.
@@ -1971,6 +1978,7 @@ signals:
 
     /**jsdoc
      * Triggered when the mouse cursor or controller laser starts hovering on an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.hoverEnterEntity
      * @param {Uuid} entityID - The ID of the entity that is being hovered.
      * @param {PointerEvent} event - Details of the event.
@@ -1980,6 +1988,7 @@ signals:
 
     /**jsdoc
      * Repeatedly triggered when the mouse cursor or controller laser moves while hovering over an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.hoverOverEntity
      * @param {Uuid} entityID - The ID of the entity that is being hovered.
      * @param {PointerEvent} event - Details of the event.
@@ -1989,6 +1998,7 @@ signals:
 
     /**jsdoc
      * Triggered when the mouse cursor or controller laser stops hovering over an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.hoverLeaveEntity
      * @param {Uuid} entityID - The ID of the entity that was being hovered.
      * @param {PointerEvent} event - Details of the event.
@@ -1999,6 +2009,7 @@ signals:
 
     /**jsdoc
      * Triggered when an avatar enters an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.enterEntity
      * @param {Uuid} entityID - The ID of the entity that the avatar entered.
      * @returns {Signal}
@@ -2032,6 +2043,7 @@ signals:
 
     /**jsdoc
      * Triggered when an avatar leaves an entity.
+     * <p>See also, {@link Script.addEventHandler}.</p>
      * @function Entities.leaveEntity
      * @param {Uuid} entityID - The ID of the entity that the avatar left.
      * @returns {Signal}

libraries/script-engine/src/ScriptEngine.cpp

@@ -987,6 +987,31 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString&
             };
         };
 
+        /**jsdoc
+         * The name of an entity event. When the entity event occurs, any function that has been registered for that event via 
+         * {@link Script.addEventHandler} is called with parameters per the entity event.
+         * <table>
+         *   <thead>
+         *     <tr><th>Event Name</th><th>Entity Event</th></tr>
+         *   </thead>
+         *   <tbody>
+         *     <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>
+         *     <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>
+         *     <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
+         *     <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
+         *     <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
+         *     <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
+         *     <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
+         *     <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
+         *     <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
+         *     <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
+         *     <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
+         *     <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
+         *   </tbody>
+         * </table>
+         *
+         * @typedef {string} Script.EntityEvent
+         */
         connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));
         connect(entities.data(), &EntityScriptingInterface::leaveEntity, this, makeSingleEntityHandler("leaveEntity"));
 
@@ -2147,7 +2172,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
 }
 
 /**jsdoc
- * Triggered when the script starts for a user.
+ * Triggered when the script starts for a user. See also, {@link Script.entityScriptPreloadFinished}.
  * <p>Note: Can only be connected to via <code>this.preload = function (...) { ... }</code> in the entity script.</p>
  * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
  * @function Entities.preload
@@ -2161,7 +2186,7 @@ void ScriptEngine::loadEntityScript(const EntityItemID& entityID, const QString&
  *         this.entityID = entityID;
  *         print("Entity ID: " + this.entityID);
  *     };
- * );
+ * });
  *
  * var entityID = Entities.addEntity({
  *     type: "Box",

libraries/script-engine/src/ScriptEngine.h

@@ -100,6 +100,8 @@ public:
 };
 
 /**jsdoc
+ * The <code>Script</code> API provides facilities for working with scripts.
+ *
  * @namespace Script
  *
  * @hifi-interface
@@ -108,7 +110,14 @@ public:
  * @hifi-server-entity
  * @hifi-assignment-client
  *
- * @property {string} context
+ * @property {string} context - The context that the script is running in:
+ *     <ul>
+ *       <li><code>"client"</code>: An Interface or avatar script.</li>
+ *       <li><code>"entity_client"</code>: A client entity script.</li>
+ *       <li><code>"entity_server"</code>: A server entity script.</li>
+ *       <li><code>"agent"</code>: An assignment client script.</li>
+ *     </ul>
+ *     <em>Read-only.</em>
  */
 class ScriptEngine : public BaseScriptEngine, public EntitiesScriptEngineProvider {
     Q_OBJECT
@@ -150,9 +159,19 @@ public:
     QList<EntityItemID> getListOfEntityScriptIDs();
 
     /**jsdoc
-     * Stop the current script.
+     * Stops and unloads the current script.
+     * <p><strong>Warning:</strong> If an assignment client script, the script gets restarted after stopping.</p>
      * @function Script.stop
-     * @param {boolean} [marshal=false]
+     * @param {boolean} [marshal=false] - Marshal.
+     *     <p class="important">Deprecated: This parameter is deprecated and will be removed.</p>
+     * @example <caption>Stop a script after 5s.</caption>
+     * Script.setInterval(function () {
+     *     print("Hello");
+     * }, 1000);
+     * 
+     * Script.setTimeout(function () {
+     *     Script.stop(true);
+     * }, 5000);
      */
     ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
     // NOTE - this is intended to be a public interface for Agent scripts, and local scripts, but not for EntityScripts
@@ -167,18 +186,20 @@ public:
 
     /**jsdoc
      * @function Script.registerGlobalObject
-     * @param {string} name
+     * @param {string} name - Name.
-     * @param {object} object
+     * @param {object} object - Object.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// registers a global object by name
     Q_INVOKABLE void registerGlobalObject(const QString& name, QObject* object);
 
     /**jsdoc
      * @function Script.registerGetterSetter
-     * @param {string} name
+     * @param {string} name - Name.
-     * @param {object} getter
+     * @param {function} getter - Getter.
-     * @param {object} setter
+     * @param {function} setter - Setter.
-     * @param {string} [parent=""]
+     * @param {string} [parent=""] - Parent.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// registers a global getter/setter
     Q_INVOKABLE void registerGetterSetter(const QString& name, QScriptEngine::FunctionSignature getter,
@@ -186,19 +207,21 @@ public:
 
     /**jsdoc
      * @function Script.registerFunction
-     * @param {string} name
+     * @param {string} name - Name.
-     * @param {object} function
+     * @param {function} function - Function.
-     * @param {number} [numArguments=-1]
+     * @param {number} [numArguments=-1] - Number of arguments.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// register a global function
     Q_INVOKABLE void registerFunction(const QString& name, QScriptEngine::FunctionSignature fun, int numArguments = -1);
 
     /**jsdoc
      * @function Script.registerFunction
-     * @param {string} parent
+     * @param {string} parent - Parent.
-     * @param {string} name
+     * @param {string} name - Name.
-     * @param {object} function
+     * @param {function} function - Function.
-     * @param {number} [numArguments=-1]
+     * @param {number} [numArguments=-1] - Number of arguments.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// register a function as a method on a previously registered global object
     Q_INVOKABLE void registerFunction(const QString& parent, const QString& name, QScriptEngine::FunctionSignature fun,
@@ -206,27 +229,30 @@ public:
 
     /**jsdoc
      * @function Script.registerValue
-     * @param {string} name
+     * @param {string} name - Name.
-     * @param {object} value
+     * @param {object} value - Value.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// registers a global object by name
     Q_INVOKABLE void registerValue(const QString& valueName, QScriptValue value);
 
     /**jsdoc
      * @function Script.evaluate
-     * @param {string} program
+     * @param {string} program - Program.
-     * @param {string} filename
+     * @param {string} filename - File name.
-     * @param {number} [lineNumber=-1]
+     * @param {number} [lineNumber=-1] - Line number.
-     * @returns {object}
+     * @returns {object} Object.
+     * @deprecated This function is deprecated and will be removed.
      */
     /// evaluate some code in the context of the ScriptEngine and return the result
     Q_INVOKABLE QScriptValue evaluate(const QString& program, const QString& fileName, int lineNumber = 1); // this is also used by the script tool widget
 
     /**jsdoc
      * @function Script.evaluateInClosure
-     * @param {object} locals
+     * @param {object} locals - Locals.
-     * @param {object} program
+     * @param {object} program - Program.
-     * @returns {object}
+     * @returns {object} Object.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE QScriptValue evaluateInClosure(const QScriptValue& locals, const QScriptProgram& program);
 
@@ -237,38 +263,53 @@ public:
     bool hasValidScriptSuffix(const QString& scriptFileName);
 
     /**jsdoc
+     * Gets the context that the script is running in: Interface/avatar, client entity, server entity, or assignment client.
      * @function Script.getContext
-     * @returns {string}
+     * @returns {string} The context that the script is running in:
+     * <ul>
+     *   <li><code>"client"</code>: An Interface or avatar script.</li>
+     *   <li><code>"entity_client"</code>: A client entity script.</li>
+     *   <li><code>"entity_server"</code>: A server entity script.</li>
+     *   <li><code>"agent"</code>: An assignment client script.</li>
+     * </ul>
      */
     Q_INVOKABLE QString getContext() const;
 
     /**jsdoc
+     * Checks whether the script is running as an Interface or avatar script.
      * @function Script.isClientScript
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the script is running as an Interface or avatar script, <code>false</code> if it 
+     *     isn't.
      */
     Q_INVOKABLE bool isClientScript() const { return _context == CLIENT_SCRIPT; }
 
     /**jsdoc
+     * Checks whether the application was compiled as a debug build.
      * @function Script.isDebugMode
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the application was compiled as a debug build, <code>false</code> if it was 
+     *     compiled as a release build.
      */
     Q_INVOKABLE bool isDebugMode() const;
 
     /**jsdoc
+     * Checks whether the script is running as a client entity script.
      * @function Script.isEntityClientScript
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the script is running as a client entity script, <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool isEntityClientScript() const { return _context == ENTITY_CLIENT_SCRIPT; }
 
     /**jsdoc
+     * Checks whether the script is running as a server entity script.
      * @function Script.isEntityServerScript
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the script is running as a server entity script, <code>false</code> if it isn't.
      */
     Q_INVOKABLE bool isEntityServerScript() const { return _context == ENTITY_SERVER_SCRIPT; }
 
     /**jsdoc
+     * Checks whether the script is running as an assignment client script.
      * @function Script.isAgentScript
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the script is running as an assignment client script, <code>false</code> if it 
+     *     isn't.
      */
     Q_INVOKABLE bool isAgentScript() const { return _context == AGENT_SCRIPT; }
 
@@ -276,25 +317,42 @@ public:
     // NOTE - these are intended to be public interfaces available to scripts
 
     /**jsdoc
+     * Adds a function to the list of functions called when an entity event occurs on a particular entity.
      * @function Script.addEventHandler
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the entity.
-     * @param {string} eventName
+     * @param {Script.EntityEvent} eventName - The name of the entity event.
-     * @param {function} handler
+     * @param {function} handler - The function to call when the entity event occurs on the entity. It can be either the name 
+     *     of a function or an in-line definition.
+     * @example <caption>Report when a mouse press occurs on a particular entity.</caption>
+     * var entityID = Entities.addEntity({
+     *     type: "Box",
+     *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+     *     dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+     *     lifetime: 300  // Delete after 5 minutes.
+     * });
+     * 
+     * function reportMousePress(entityID, event) {
+     *     print("Mouse pressed on entity: " + JSON.stringify(event));
+     * }
+     * 
+     * Script.addEventHandler(entityID, "mousePressOnEntity", reportMousePress);
      */
     Q_INVOKABLE void addEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler);
 
     /**jsdoc
+     * Removes a function from the list of functions called when an entity event occurs on a particular entity.
      * @function Script.removeEventHandler
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the entity.
-     * @param {string} eventName
+     * @param {Script.EntityEvent} eventName - The name of the entity event.
-     * @param {function} handler
+     * @param {function} handler - The name of the function to no longer call when the entity event occurs on the entity.
      */
     Q_INVOKABLE void removeEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler);
 
     /**jsdoc
-     * Start a new Interface or entity script.
+     * Starts running another script in Interface.
+     * <table><tr><th>Available in:</th><td>Interface Scripts</td><td>Avatar Scripts</td></tr></table>
      * @function Script.load
-     * @param {string} filename - The URL of the script to load. Can be relative to the current script.
+     * @param {string} filename - The URL of the script to load. This can be relative to the current script's URL.
      * @example <caption>Load a script from another script.</caption>
      * // First file: scriptA.js
      * print("This is script A");
@@ -303,7 +361,7 @@ public:
      * print("This is script B");
      * Script.load("scriptA.js");
      *
-     * // If you run scriptB.js you should see both scripts in the running scripts list.
+     * // If you run scriptB.js you should see both scripts in the Running Scripts dialog.
      * // And you should see the following output:
      * // This is script B
      * // This is script A
@@ -311,22 +369,24 @@ public:
     Q_INVOKABLE void load(const QString& loadfile);
 
     /**jsdoc
-     * Include JavaScript from other files in the current script. If a callback is specified the files are loaded and included 
+     * Includes JavaScript from other files in the current script. If a callback is specified, the files are loaded and 
-     * asynchronously, otherwise they are included synchronously (i.e., script execution blocks while the files are included).
+     * included asynchronously, otherwise they are included synchronously (i.e., script execution blocks while the files are 
+     * included).
      * @function Script.include
+     * @variation 0
      * @param {string[]} filenames - The URLs of the scripts to include. Each can be relative to the current script.
-     * @param {function} [callback=null] - The function to call back when the scripts have been included. Can be an in-line 
+     * @param {function} [callback=null] - The function to call back when the scripts have been included. It can be either the 
-     * function or the name of a function.
+     *     name of a function or an in-line definition.
      */
     Q_INVOKABLE void include(const QStringList& includeFiles, QScriptValue callback = QScriptValue());
 
     /**jsdoc
-     * Include JavaScript from another file in the current script. If a callback is specified the file is loaded and included 
+     * Includes JavaScript from another file in the current script. If a callback is specified, the file is loaded and included
      * asynchronously, otherwise it is included synchronously (i.e., script execution blocks while the file is included).
      * @function Script.include
-     * @param {string} filename - The URL of the script to include. Can be relative to the current script.
+     * @param {string} filename - The URL of the script to include. It can be relative to the current script.
-     * @param {function} [callback=null] - The function to call back when the script has been included. Can be an in-line 
+     * @param {function} [callback=null] - The function to call back when the script has been included. It can be either the 
-     * function or the name of a function.
+     *     name of a function or an in-line definition.
      * @example <caption>Include a script file asynchronously.</caption>
      * // First file: scriptA.js
      * print("This is script A");
@@ -349,16 +409,21 @@ public:
     // MODULE related methods
 
     /**jsdoc
+     * Provides access to methods or objects provided in an external JavaScript or JSON file. 
+     * See {@link https://docs.highfidelity.com/script/js-tips.html} for further details.
      * @function Script.require
-     * @param {string} module
+     * @param {string} module - The module to use. May be a JavaScript file or the name of a system module such as 
+     *     <code>"sppUi"</code>.
      */
     Q_INVOKABLE QScriptValue require(const QString& moduleId);
 
     /**jsdoc
      * @function Script.resetModuleCache
-     * @param {boolean} [deleteScriptCache=false]
+     * @param {boolean} [deleteScriptCache=false] - Delete script cache.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void resetModuleCache(bool deleteScriptCache = false);
+
     QScriptValue currentModule();
     bool registerModuleWithParent(const QScriptValue& module, const QScriptValue& parent);
     QScriptValue newModule(const QString& modulePath, const QScriptValue& parent = QScriptValue());
@@ -366,53 +431,53 @@ public:
     QScriptValue instantiateModule(const QScriptValue& module, const QString& sourceCode);
 
     /**jsdoc
-     * Call a function at a set interval.
+     * Calls a function repeatedly, at a set interval.
      * @function Script.setInterval
-     * @param {function} function - The function to call. Can be an in-line function or the name of a function.
+     * @param {function} function - The function to call. This can be either the name of a function or an in-line definition.
      * @param {number} interval - The interval at which to call the function, in ms.
-     * @returns {object} A handle to the interval timer. Can be used by {@link Script.clearInterval}.
+     * @returns {object} A handle to the interval timer. This can be used in {@link Script.clearInterval}.
      * @example <caption>Print a message every second.</caption>
      * Script.setInterval(function () {
-     *     print("Timer fired");
+     *     print("Interval timer fired");
      * }, 1000);
     */
     Q_INVOKABLE QObject* setInterval(const QScriptValue& function, int intervalMS);
 
     /**jsdoc
-     * Call a function after a delay.
+     * Calls a function once, after a delay.
      * @function Script.setTimeout
-     * @param {function} function - The function to call. Can be an in-line function or the name of a function.
+     * @param {function} function - The function to call. This can be either the name of a function or an in-line definition.
      * @param {number} timeout - The delay after which to call the function, in ms.
-     * @returns {object} A handle to the timeout timer. Can be used by {@link Script.clearTimeout}.
+     * @returns {object} A handle to the timeout timer. This can be used in {@link Script.clearTimeout}.
-     * @example <caption>Print a message after a second.</caption>
+     * @example <caption>Print a message once, after a second.</caption>
      * Script.setTimeout(function () {
-     *     print("Timer fired");
+     *     print("Timeout timer fired");
      * }, 1000);
      */
     Q_INVOKABLE QObject* setTimeout(const QScriptValue& function, int timeoutMS);
 
     /**jsdoc
-     * Stop an interval timer set by {@link Script.setInterval|setInterval}.
+     * Stops an interval timer set by {@link Script.setInterval|setInterval}.
      * @function Script.clearInterval
-     * @param {object} timer - The interval timer to clear.
+     * @param {object} timer - The interval timer to stop.
      * @example <caption>Stop an interval timer.</caption>
      * // Print a message every second.
      * var timer = Script.setInterval(function () {
-     *     print("Timer fired");
+     *     print("Interval timer fired");
      * }, 1000);
      *
      * // Stop the timer after 10 seconds.
      * Script.setTimeout(function () {
-     *     print("Stop timer");
+     *     print("Stop interval timer");
      *     Script.clearInterval(timer);
      * }, 10000);
      */
     Q_INVOKABLE void clearInterval(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); }
 
     /**jsdoc
-     * Clear a timeout timer set by {@link Script.setTimeout|setTimeout}.
+     * Stops a timeout timer set by {@link Script.setTimeout|setTimeout}.
      * @function Script.clearTimeout
-     * @param {object} timer - The timeout timer to clear.
+     * @param {object} timer - The timeout timer to stop.
      * @example <caption>Stop a timeout timer.</caption>
      * // Print a message after two seconds.
      * var timer = Script.setTimeout(function () {
@@ -425,34 +490,53 @@ public:
     Q_INVOKABLE void clearTimeout(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); }
 
     /**jsdoc
+     * Prints a message to the program log.
+     * <p>Alternatively, you can use {@link print}, {@link console.log}, or one of the other {@link console} methods.</p>
      * @function Script.print
-     * @param {string} message
+     * @param {string} message - The message to print.
+     */
+    /**jsdoc
+     * Prints a message to the program log.
+     * <p>This is an alias of {@link Script.print}.</p>
+     * @function print
+     * @param {string} message - The message to print.
      */
     Q_INVOKABLE void print(const QString& message);
 
     /**jsdoc
-     * Resolve a relative path to an absolute path.
+     * Resolves a relative path to an absolute path. The relative path is relative to the script's location.
      * @function Script.resolvePath
      * @param {string} path - The relative path to resolve.
      * @returns {string} The absolute path.
+     * @example <caption>Report the directory and filename of the running script.</caption>
+     * print(Script.resolvePath(""));
+     * @example <caption>Report the directory of the running script.</caption>
+     * print(Script.resolvePath("."));
+     * @example <caption>Report the path to a file located relative to the running script.</caption>
+     * print(Script.resolvePath("../assets/sounds/hello.wav"));
      */
     Q_INVOKABLE QUrl resolvePath(const QString& path) const;
 
     /**jsdoc
+     * Gets the path to the resources directory for QML files.
      * @function Script.resourcesPath
-     * @returns {string}
+     * @returns {string} The path to the resources directory for QML files.
      */
     Q_INVOKABLE QUrl resourcesPath() const;
 
     /**jsdoc
+     * Starts timing a section of code in order to send usage data about it to High Fidelity. Shouldn't be used outside of the 
+     * standard scripts.
      * @function Script.beginProfileRange
-     * @param {string} label
+     * @param {string} label - A name that identifies the section of code.
      */
     Q_INVOKABLE void beginProfileRange(const QString& label) const;
 
     /**jsdoc
+     * Finishes timing a section of code in order to send usage data about it to High Fidelity. Shouldn't be used outside of 
+     * the standard scripts.
      * @function Script.endProfileRange
-     * @param {string} label
+     * @param {string} label - A name that identifies the section of code.
      */
     Q_INVOKABLE void endProfileRange(const QString& label) const;
 
@@ -460,9 +544,10 @@ public:
     // Entity Script Related methods
 
     /**jsdoc
+     * Checks whether an entity has an entity script running.
      * @function Script.isEntityScriptRunning
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the entity.
-     * @returns {boolean}
+     * @returns {boolean} <code>true</code> if the entity has an entity script running, <code>false</code> if it doesn't.
      */
     Q_INVOKABLE bool isEntityScriptRunning(const EntityItemID& entityID) {
         QReadLocker locker { &_entityScriptsLock };
@@ -474,60 +559,71 @@ public:
 
     /**jsdoc
      * @function Script.loadEntityScript
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - Entity ID.
-     * @param {string} script
+     * @param {string} script - Script.
-     * @param {boolean} forceRedownload
+     * @param {boolean} forceRedownload - Force re-download.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void loadEntityScript(const EntityItemID& entityID, const QString& entityScript, bool forceRedownload);
 
     /**jsdoc
      * @function Script.unloadEntityScript
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - Entity ID.
-     * @param {boolean} [shouldRemoveFromMap=false]
+     * @param {boolean} [shouldRemoveFromMap=false] - Should remove from map.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void unloadEntityScript(const EntityItemID& entityID, bool shouldRemoveFromMap = false); // will call unload method
 
     /**jsdoc
      * @function Script.unloadAllEntityScripts
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void unloadAllEntityScripts();
 
     /**jsdoc
+     * Calls a method in an entity script.
      * @function Script.callEntityScriptMethod
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - The ID of the entity running the entity script.
-     * @param {string} methodName
+     * @param {string} methodName - The name of the method to call.
-     * @param {string[]} parameters
+     * @param {string[]} [parameters=[]] - The parameters to call the specified method with.
-     * @param {Uuid} [remoteCallerID=Uuid.NULL]
+     * @param {Uuid} [remoteCallerID=Uuid.NULL] - An ID that identifies the caller.
      */
     Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName,
                                             const QStringList& params = QStringList(),
                                             const QUuid& remoteCallerID = QUuid()) override;
 
     /**jsdoc
+     * Calls a method in an entity script.
      * @function Script.callEntityScriptMethod
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - Entity ID.
-     * @param {string} methodName
+     * @param {string} methodName - Method name.
-     * @param {PointerEvent} event
+     * @param {PointerEvent} event - Pointer event.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const PointerEvent& event);
 
     /**jsdoc
+     * Calls a method in an entity script.
      * @function Script.callEntityScriptMethod
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - Entity ID.
-     * @param {string} methodName
+     * @param {string} methodName - Method name.
-     * @param {Uuid} otherID
+     * @param {Uuid} otherID - Other entity ID.
-     * @param {Collision} collision
+     * @param {Collision} collision - Collision.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, const EntityItemID& otherID, const Collision& collision);
 
     /**jsdoc
+     * Manually runs the JavaScript garbage collector which reclaims memory by disposing of objects that are no longer 
+     * reachable.
      * @function Script.requestGarbageCollection
      */
     Q_INVOKABLE void requestGarbageCollection() { collectGarbage(); }
 
     /**jsdoc
      * @function Script.generateUUID
-     * @returns {Uuid}
+     * @returns {Uuid} A new UUID.
+     * @deprecated This function is deprecated and will be removed. Use {@link Uuid.generate} instead.
      */
     Q_INVOKABLE QUuid generateUUID() { return QUuid::createUuid(); }
 
@@ -573,7 +669,7 @@ public slots:
 
     /**jsdoc
      * @function Script.callAnimationStateHandler
-     * @param {function} callback - Callback.
+     * @param {function} callback - Callback function.
      * @param {object} parameters - Parameters.
      * @param {string[]} names - Names.
      * @param {boolean} useNames - Use names.
@@ -584,7 +680,8 @@ public slots:
 
     /**jsdoc
      * @function Script.updateMemoryCost
-     * @param {number} deltaSize
+     * @param {number} deltaSize - Delta size.
+     * @deprecated This function is deprecated and will be removed.
      */
     void updateMemoryCost(const qint64&);
 
@@ -592,31 +689,37 @@ signals:
 
     /**jsdoc
      * @function Script.scriptLoaded
-     * @param {string} filename
+     * @param {string} filename - File name.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void scriptLoaded(const QString& scriptFilename);
 
     /**jsdoc
      * @function Script.errorLoadingScript
-     * @param {string} filename
+     * @param {string} filename - File name.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void errorLoadingScript(const QString& scriptFilename);
 
     /**jsdoc
-     * Triggered regularly at a system-determined frequency.
+     * Triggered frequently at a system-determined interval.
      * @function Script.update
      * @param {number} deltaTime - The time since the last update, in s.
      * @returns {Signal}
+     * @example <caption>Report script update intervals.</caption>
+     * Script.update.connect(function (deltaTime) {
+     *     print("Update: " + deltaTime);
+     * });
      */
     void update(float deltaTime);
 
     /**jsdoc
-     * Triggered when the script is ending.
+     * Triggered when the script is stopping.
      * @function Script.scriptEnding
      * @returns {Signal}
-     * @example <caption>Connect to the <code>scriptEnding</code> signal.</caption>
+     * @example <caption>Report when a script is stopping.</caption>
      * print("Script started");
      *
      * Script.scriptEnding.connect(function () {
@@ -632,52 +735,60 @@ signals:
 
     /**jsdoc
      * @function Script.finished
-     * @param {string} filename
+     * @param {string} filename - File name.
-     * @param {object} engine
+     * @param {object} engine - Engine.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void finished(const QString& fileNameString, ScriptEnginePointer);
 
     /**jsdoc
      * @function Script.cleanupMenuItem
-     * @param {string} menuItem
+     * @param {string} menuItem - Menu item.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void cleanupMenuItem(const QString& menuItemString);
 
     /**jsdoc
+     * Triggered when a script prints a message to the program log via {@link Script.print}, {@link  print}, 
+     * {@link console.log}, {@link console.info}, {@link console.warn}, {@link console.error}, or {@link console.debug}.
      * @function Script.printedMessage
-     * @param {string} message
+     * @param {string} message - The message.
-     * @param {string} scriptName
+     * @param {string} scriptName - The name of the script that generated the message.
      * @returns {Signal}
      */
     void printedMessage(const QString& message, const QString& scriptName);
 
     /**jsdoc
+     * Triggered when a script generates an error or {@link console.error} is called.
      * @function Script.errorMessage
-     * @param {string} message
+     * @param {string} message - The error message.
-     * @param {string} scriptName
+     * @param {string} scriptName - The name of the script that generated the error message.
      * @returns {Signal}
      */
     void errorMessage(const QString& message, const QString& scriptName);
 
     /**jsdoc
+     * Triggered when a script generates a warning or {@link console.warn} is called.
      * @function Script.warningMessage
-     * @param {string} message
+     * @param {string} message - The warning message.
-     * @param {string} scriptName
+     * @param {string} scriptName - The name of the script that generated the warning message.
      * @returns {Signal}
      */
     void warningMessage(const QString& message, const QString& scriptName);
 
     /**jsdoc
+     * Triggered when a script generates an information message or {@link console.info} is called.
      * @function Script.infoMessage
-     * @param {string} message
+     * @param {string} message - The information message.
-     * @param {string} scriptName
+     * @param {string} scriptName - The name of the script that generated the information message.
      * @returns {Signal}
      */
     void infoMessage(const QString& message, const QString& scriptName);
 
     /**jsdoc
+     * Triggered when the running state of the script changes, e.g., from running to stopping.
      * @function Script.runningStateChanged
      * @returns {Signal}
      */
@@ -686,26 +797,30 @@ signals:
     /**jsdoc
      * @function Script.clearDebugWindow
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void clearDebugWindow();
 
     /**jsdoc
      * @function Script.loadScript
-     * @param {string} scriptName
+     * @param {string} scriptName - Script name.
-     * @param {boolean} isUserLoaded
+     * @param {boolean} isUserLoaded - Is user loaded.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void loadScript(const QString& scriptName, bool isUserLoaded);
 
     /**jsdoc
      * @function Script.reloadScript
-     * @param {string} scriptName
+     * @param {string} scriptName - Script name.
-     * @param {boolean} isUserLoaded
+     * @param {boolean} isUserLoaded - Is user loaded.
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void reloadScript(const QString& scriptName, bool isUserLoaded);
 
     /**jsdoc
+     * Triggered when the script has stopped.
      * @function Script.doneRunning
      * @returns {Signal}
      */
@@ -714,14 +829,35 @@ signals:
     /**jsdoc
      * @function Script.entityScriptDetailsUpdated
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     // Emitted when an entity script is added or removed, or when the status of an entity
     // script is updated (goes from RUNNING to ERROR_RUNNING_SCRIPT, for example)
     void entityScriptDetailsUpdated();
 
     /**jsdoc
+     * Triggered when the script starts for the user. See also, {@link Entities.preload}.
+     * <table><tr><th>Available in:</th><td>Client Entity Scripts</td><td>Server Entity Scripts</td></tr></table>
      * @function Script.entityScriptPreloadFinished
+     * @param {Uuid} entityID - The ID of the entity that the script is running in.
      * @returns {Signal}
+     * @example <caption>Get the ID of the entity that a client entity script is running in.</caption>
+     * var entityScript = (function () {
+     *     this.entityID = Uuid.NULL;
+     *
+     * Script.entityScriptPreloadFinished.connect(function (entityID) {
+     *     this.entityID = entityID;
+     *     print("Entity ID: " + this.entityID);
+     * });
+     *
+     * var entityID = Entities.addEntity({
+     *     type: "Box",
+     *     position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
+     *     dimensions: { x: 0.5, y: 0.5, z: 0.5 },
+     *     color: { red: 255, green: 0, blue: 0 },
+     *     script: "(" + entityScript + ")",  // Could host the script on a Web server instead.
+     *     lifetime: 300  // Delete after 5 minutes.
+     * });
      */
     // Emitted when an entity script has finished running preload
     void entityScriptPreloadFinished(const EntityItemID& entityID);
@@ -731,16 +867,18 @@ protected:
 
     /**jsdoc
      * @function Script.executeOnScriptThread
-     * @param {object} function
+     * @param {function} function - Function.
-     * @param {ConnectionType} [type=2]
+     * @param {ConnectionType} [type=2] - Connection type.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void executeOnScriptThread(std::function<void()> function, const Qt::ConnectionType& type = Qt::QueuedConnection );
 
     /**jsdoc
      * @function Script._requireResolve
-     * @param {string} module
+     * @param {string} module - Module.
-     * @param {string} [relativeTo=""]
+     * @param {string} [relativeTo=""] - Relative to.
-     * @returns {string}
+     * @returns {string} Result.
+     * @deprecated This function is deprecated and will be removed.
      */
     // note: this is not meant to be called directly, but just to have QMetaObject take care of wiring it up in general;
     //   then inside of init() we just have to do "Script.require.resolve = Script._requireResolve;"
@@ -763,12 +901,13 @@ protected:
 
     /**jsdoc
      * @function Script.entityScriptContentAvailable
-     * @param {Uuid} entityID
+     * @param {Uuid} entityID - Entity ID.
-     * @param {string} scriptOrURL
+     * @param {string} scriptOrURL - Path.
-     * @param {string} contents
+     * @param {string} contents - Contents.
-     * @param {boolean} isURL
+     * @param {boolean} isURL - Is a URL.
-     * @param {boolean} success
+     * @param {boolean} success - Success.
-     * @param {string} status
+     * @param {string} status - Status.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void entityScriptContentAvailable(const EntityItemID& entityID, const QString& scriptOrURL, const QString& contents, bool isURL, bool success, const QString& status);
 

libraries/shared/src/BaseScriptEngine.h

@@ -31,8 +31,32 @@ public:
 
     BaseScriptEngine() {}
 
+    /**jsdoc
+     * @function Script.lintScript
+     * @param {string} sourceCode - Source code.
+     * @param {string} fileName - File name.
+     * @param {number} [lineNumber=1] - Line number.
+     * @returns {object} Object.
+     * @deprecated This function is deprecated and will be removed.
+     */
     Q_INVOKABLE QScriptValue lintScript(const QString& sourceCode, const QString& fileName, const int lineNumber = 1);
+
+    /**jsdoc
+     * @function Script.makeError
+     * @param {object} [other] - Other.
+     * @param {string} [type="Error"] - Error.
+     * @returns {object} Object.
+     * @deprecated This function is deprecated and will be removed.
+     */
     Q_INVOKABLE QScriptValue makeError(const QScriptValue& other = QScriptValue(), const QString& type = "Error");
+    
+    /**jsdoc
+     * @function Script.formatExecption
+     * @param {object} exception - Exception.
+     * @param {boolean} inludeExtendeDetails - Include extended details.
+     * @returns {string} String.
+     * @deprecated This function is deprecated and will be removed.
+     */
     Q_INVOKABLE QString formatException(const QScriptValue& exception, bool includeExtendedDetails);
 
     QScriptValue cloneUncaughtException(const QString& detail = QString());
@@ -48,6 +72,25 @@ public:
     // helper to detect and log warnings when other code invokes QScriptEngine/BaseScriptEngine in thread-unsafe ways
     static bool IS_THREADSAFE_INVOCATION(const QThread *thread, const QString& method);
 signals:
+    /**jsdoc
+     * @function Script.signalHandlerException
+     * @param {object} exception - Exception.
+     * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
+     */
+    // Script.signalHandlerException is exposed by QScriptEngine.
+    
+    /**jsdoc
+     * Triggered when a script generates an unhandled exception.
+     * @function Script.unhandledException
+     * @param {object} exception - The details of the exception.
+     * @returns {Signal}
+     * @example <caption>Report the details of an unhandled exception.</caption>
+     * Script.unhandledException.connect(function (exception) {
+     *     print("Unhandled exception: " + JSON.stringify(exception));
+     * });
+     * var properties = JSON.parse("{ x: 1"); // Invalid JSON string.
+     */
     void unhandledException(const QScriptValue& exception);
 
 protected: