From 0e478de1a28216b6df4ea5ca05fd7da4851ee599 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 8 May 2019 10:47:06 +1200 Subject: [PATCH 1/5] Stub out missing Script JSDoc --- libraries/script-engine/src/ScriptEngine.h | 4 ++- libraries/shared/src/BaseScriptEngine.h | 33 ++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 3549578ed5..c4d4dd2c31 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -359,6 +359,7 @@ public: * @param {boolean} [deleteScriptCache=false] */ 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()); @@ -496,7 +497,7 @@ public: * @function Script.callEntityScriptMethod * @param {Uuid} entityID * @param {string} methodName - * @param {string[]} parameters + * @param {string[]} [parameters=[]] * @param {Uuid} [remoteCallerID=Uuid.NULL] */ Q_INVOKABLE void callEntityScriptMethod(const EntityItemID& entityID, const QString& methodName, @@ -721,6 +722,7 @@ signals: /**jsdoc * @function Script.entityScriptPreloadFinished + * @param {Uuid} entityID * @returns {Signal} */ // Emitted when an entity script has finished running preload diff --git a/libraries/shared/src/BaseScriptEngine.h b/libraries/shared/src/BaseScriptEngine.h index 8820a386bf..0a1addaa2e 100644 --- a/libraries/shared/src/BaseScriptEngine.h +++ b/libraries/shared/src/BaseScriptEngine.h @@ -31,8 +31,29 @@ public: BaseScriptEngine() {} + /**jsdoc + * @function Script.lintScript + * @param {string} sourceCode + * @param {string} fileName + * @param {number} [lineNumber=1] + * @returns {object} + */ Q_INVOKABLE QScriptValue lintScript(const QString& sourceCode, const QString& fileName, const int lineNumber = 1); + + /**jsdoc + * @function Script.makeError + * @param {object} [other] + * @param {string} [type="Error"] + * @returns {object} + */ Q_INVOKABLE QScriptValue makeError(const QScriptValue& other = QScriptValue(), const QString& type = "Error"); + + /**jsdoc + * @function Script.formatExecption + * @param {object} exception + * @param {boolean} inludeExtendeDetails + * @returns {string} + */ Q_INVOKABLE QString formatException(const QScriptValue& exception, bool includeExtendedDetails); QScriptValue cloneUncaughtException(const QString& detail = QString()); @@ -48,6 +69,18 @@ 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 + * @returns {Signal} + */ + // Script.signalHandlerException is exposed by QScriptEngine. + + /**jsdoc + * @function Script.unhandledException + * @param {object} exception + * @returns {Signal} + */ void unhandledException(const QScriptValue& exception); protected: From d196e357012b61394067b3a25d7a467b32578115 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 10 May 2019 08:33:03 +1200 Subject: [PATCH 2/5] Polish existing Script JSDoc --- libraries/script-engine/src/ScriptEngine.h | 84 ++++++++++++++-------- 1 file changed, 54 insertions(+), 30 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index c4d4dd2c31..36e115411c 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -100,6 +100,8 @@ public: }; /**jsdoc + * The Script API provides facilities for working with scripts. + * * @namespace Script * * @hifi-interface @@ -150,9 +152,18 @@ public: QList getListOfEntityScriptIDs(); /**jsdoc - * Stop the current script. + * Stops and unloads the current script. * @function Script.stop - * @param {boolean} [marshal=false] + * @param {boolean} [marshal=false] - Marshal. + *

Deprecated: This parameter is deprecated and will be removed.

+ * @example Stop a script after 5s. + * 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 @@ -292,9 +303,10 @@ public: 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. + *

Note: Only works for Interface and avatar scripts.

* @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 Load a script from another script. * // First file: scriptA.js * print("This is script A"); @@ -303,7 +315,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,21 +323,23 @@ 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 - * asynchronously, otherwise they are included synchronously (i.e., script execution blocks while the files are included). + * Includes JavaScript from other files in the current script. If a callback is specified, the files are loaded and + * 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 an in-line * function or the name of a function. */ 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 {function} [callback=null] - The function to call back when the script has been included. Can be an in-line + * @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. It can be an in-line * function or the name of a function. * @example Include a script file asynchronously. * // First file: scriptA.js @@ -367,53 +381,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 an in-line function or the name of a function. * @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 by {@link Script.clearInterval}. * @example Print a message every second. * 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 an in-line function or the name of a function. * @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}. - * @example Print a message after a second. + * @returns {object} A handle to the timeout timer. This can be used by {@link Script.clearTimeout}. + * @example Print a message once, after a second. * 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 Stop an interval timer. * // 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(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 Stop a timeout timer. * // Print a message after two seconds. * var timer = Script.setTimeout(function () { @@ -432,10 +446,16 @@ public: 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 Report the directory and filename of the running script. + * print(Script.resolvePath("")); + * @example Report the directory of the running script. + * print(Script.resolvePath(".")); + * @example Report the path to a file located relative to the running script. + * print(Script.resolvePath("../assets/sounds/hello.wav")); */ Q_INVOKABLE QUrl resolvePath(const QString& path) const; @@ -606,18 +626,22 @@ signals: 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 Report script update intervals. + * 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 Connect to the scriptEnding signal. + * @example Report when a script is stopping. * print("Script started"); * * Script.scriptEnding.connect(function () { From 0a0a25139c09dbcc6ebf3bec29ad4391cd0f0d69 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 11 May 2019 09:29:13 +1200 Subject: [PATCH 3/5] Deprecate items that shouldn't be in the Script API --- libraries/script-engine/src/ScriptEngine.h | 105 ++++++++++++--------- libraries/shared/src/BaseScriptEngine.h | 17 ++-- 2 files changed, 72 insertions(+), 50 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 36e115411c..b81829aa54 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -178,18 +178,20 @@ public: /**jsdoc * @function Script.registerGlobalObject - * @param {string} name - * @param {object} object + * @param {string} name - Name. + * @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 {object} getter - * @param {object} setter - * @param {string} [parent=""] + * @param {string} name - Name. + * @param {object} getter - Getter. + * @param {object} setter - Setter. + * @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, @@ -197,19 +199,21 @@ public: /**jsdoc * @function Script.registerFunction - * @param {string} name - * @param {object} function - * @param {number} [numArguments=-1] + * @param {string} name - Name. + * @param {object} function - Function. + * @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} name - * @param {object} function - * @param {number} [numArguments=-1] + * @param {string} parent - Parent. + * @param {string} name - Name. + * @param {object} function - Function. + * @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, @@ -217,27 +221,30 @@ public: /**jsdoc * @function Script.registerValue - * @param {string} name - * @param {object} value + * @param {string} name - Name. + * @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} filename - * @param {number} [lineNumber=-1] - * @returns {object} + * @param {string} program - Program. + * @param {string} filename - File name. + * @param {number} [lineNumber=-1] - Line number. + * @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} program - * @returns {object} + * @param {object} locals - Locals. + * @param {object} program - Program. + * @returns {object} Object. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE QScriptValue evaluateInClosure(const QScriptValue& locals, const QScriptProgram& program); @@ -495,21 +502,24 @@ public: /**jsdoc * @function Script.loadEntityScript - * @param {Uuid} entityID - * @param {string} script - * @param {boolean} forceRedownload + * @param {Uuid} entityID - Entity IUD. + * @param {string} script - Script. + * @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 {boolean} [shouldRemoveFromMap=false] + * @param {Uuid} entityID - Entity ID. + * @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(); @@ -548,7 +558,8 @@ public: /**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(); } @@ -605,7 +616,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&); @@ -657,16 +669,18 @@ signals: /**jsdoc * @function Script.finished - * @param {string} filename - * @param {object} engine + * @param {string} filename - File name. + * @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); @@ -711,6 +725,7 @@ signals: /**jsdoc * @function Script.clearDebugWindow * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ void clearDebugWindow(); @@ -739,6 +754,7 @@ 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) @@ -757,16 +773,18 @@ protected: /**jsdoc * @function Script.executeOnScriptThread - * @param {object} function - * @param {ConnectionType} [type=2] + * @param {object} function - Function. + * @param {ConnectionType} [type=2] - Connection type. + * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void executeOnScriptThread(std::function function, const Qt::ConnectionType& type = Qt::QueuedConnection ); /**jsdoc * @function Script._requireResolve - * @param {string} module - * @param {string} [relativeTo=""] - * @returns {string} + * @param {string} module - Module. + * @param {string} [relativeTo=""] - Relative to. + * @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;" @@ -789,12 +807,13 @@ protected: /**jsdoc * @function Script.entityScriptContentAvailable - * @param {Uuid} entityID - * @param {string} scriptOrURL - * @param {string} contents - * @param {boolean} isURL - * @param {boolean} success - * @param {string} status + * @param {Uuid} entityID - Entity ID. + * @param {string} scriptOrURL - Path. + * @param {string} contents - Contents. + * @param {boolean} isURL - Is URL. + * @param {boolean} success - Success. + * @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); diff --git a/libraries/shared/src/BaseScriptEngine.h b/libraries/shared/src/BaseScriptEngine.h index 0a1addaa2e..6baa5d3c35 100644 --- a/libraries/shared/src/BaseScriptEngine.h +++ b/libraries/shared/src/BaseScriptEngine.h @@ -42,17 +42,19 @@ public: /**jsdoc * @function Script.makeError - * @param {object} [other] - * @param {string} [type="Error"] - * @returns {object} + * @param {object} [other] - Other. + * @param {string} [type="Error"] - Errorl + * @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 - * @param {boolean} inludeExtendeDetails - * @returns {string} + * @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); @@ -71,8 +73,9 @@ public: signals: /**jsdoc * @function Script.signalHandlerException - * @param {object} exception + * @param {object} exception - Exception. * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ // Script.signalHandlerException is exposed by QScriptEngine. From ca7ddece8b1dc6c763dfc4c226836cc367522f43 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 21 May 2019 09:49:21 +1200 Subject: [PATCH 4/5] Add missing Script JSDoc --- .../entities/src/EntityScriptingInterface.h | 12 ++ libraries/script-engine/src/ScriptEngine.cpp | 29 ++- libraries/script-engine/src/ScriptEngine.h | 202 +++++++++++++----- libraries/shared/src/BaseScriptEngine.h | 17 +- 4 files changed, 199 insertions(+), 61 deletions(-) diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index c072dedaf9..39700bfc31 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @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. + *

See also, {@link Script.addEventHandler}.

* @function Entities.leaveEntity * @param {Uuid} entityID - The ID of the entity that the avatar left. * @returns {Signal} diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp index 7abb63ca1c..309161206c 100644 --- a/libraries/script-engine/src/ScriptEngine.cpp +++ b/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. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Event NameEntity Event
"enterEntity"{@link Entities.enterEntity}
"leaveEntity"{@link Entities.leaveEntity}
"mousePressOnEntity"{@link Entities.mousePressOnEntity}
"mouseMoveOnEntity"{@link Entities.mouseMoveOnEntity}
"mouseReleaseOnEntity"{@link Entities.mouseReleaseOnEntity}
"clickDownOnEntity"{@link Entities.clickDownOnEntity}
"holdingClickOnEntity"{@link Entities.holdingClickOnEntity}
"clickReleaseOnEntity"{@link Entities.clickReleaseOnEntity}
"hoverEnterEntity"{@link Entities.hoverEnterEntity}
"hoverOverEntity"{@link Entities.hoverOverEntity}
"hoverLeaveEntity"{@link Entities.hoverLeaveEntity}
"collisionWithEntity"{@link Entities.collisionWithEntity}
+ * + * @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}. *

Note: Can only be connected to via this.preload = function (...) { ... } in the entity script.

*
Available in:Client Entity ScriptsServer Entity Scripts
* @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", diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index b81829aa54..c6b1135fc6 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -110,7 +110,14 @@ public: * @hifi-server-entity * @hifi-assignment-client * - * @property {string} context + * @property {string} context - The context that the script is running in: + *
    + *
  • "client": An Interface or avatar script.
    • + *
  • "entity_client": A client entity script.
    • + *
  • "entity_server": A server entity script.
    • + *
  • "agent": An assignment client script.
    • + *
+ * Read-only. */ class ScriptEngine : public BaseScriptEngine, public EntitiesScriptEngineProvider { Q_OBJECT @@ -153,6 +160,7 @@ public: /**jsdoc * Stops and unloads the current script. + *

Warning: If an assignment client script, the script gets restarted after stopping.

* @function Script.stop * @param {boolean} [marshal=false] - Marshal. *

Deprecated: This parameter is deprecated and will be removed.

@@ -255,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: + *
    + *
  • "client": An Interface or avatar script.
    • + *
  • "entity_client": A client entity script.
    • + *
  • "entity_server": A server entity script.
    • + *
  • "agent": An assignment client script.
    • + *
*/ 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} true if the script is running as an Interface or avatar script, false 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} true if the software was compiled as a debug build, false if it was + * compiled as a release build. */ Q_INVOKABLE bool isDebugMode() const; /**jsdoc + * Checks whether the script content is a client entity script. * @function Script.isEntityClientScript - * @returns {boolean} + * @returns {boolean} true if the script is running as a client entity script, false if it isn't. */ Q_INVOKABLE bool isEntityClientScript() const { return _context == ENTITY_CLIENT_SCRIPT; } /**jsdoc + * Checks whether the script context is a server entity script. * @function Script.isEntityServerScript - * @returns {boolean} + * @returns {boolean} true if the script is running as a server entity script, false 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} true if the script is running as an assignment client script, false if it + * isn't. */ Q_INVOKABLE bool isAgentScript() const { return _context == AGENT_SCRIPT; } @@ -294,24 +317,40 @@ public: // NOTE - these are intended to be public interfaces available to scripts /**jsdoc + * Adds a function to the list of functions called upon the occurrence of an entity event on a particular entity. * @function Script.addEventHandler - * @param {Uuid} entityID - * @param {string} eventName - * @param {function} handler + * @param {Uuid} entityID - The ID of the entity. + * @param {Script.EntityEvent} eventName - The name of the entity event. + * @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 Report when a mouse press occurs on a particular entity. + * 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 upon the occurrence of an entity event on a particular entity. * @function Script.removeEventHandler - * @param {Uuid} entityID - * @param {string} eventName - * @param {function} handler + * @param {Uuid} entityID - The ID of the entity. + * @param {Script.EntityEvent} eventName - The name of the entity event. + * @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 * Starts running another script in Interface. - *

Note: Only works for Interface and avatar scripts.

+ *
Available in:Interface ScriptsAvatar Scripts
* @function Script.load * @param {string} filename - The URL of the script to load. This can be relative to the current script's URL. * @example Load a script from another script. @@ -336,8 +375,8 @@ public: * @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. It can be an in-line - * function or the name of a function. + * @param {function} [callback=null] - The function to call back when the scripts have been included. It can be either the + * name of a function or an in-line definition. */ Q_INVOKABLE void include(const QStringList& includeFiles, QScriptValue callback = QScriptValue()); @@ -346,8 +385,8 @@ public: * 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. It can be relative to the current script. - * @param {function} [callback=null] - The function to call back when the script has been included. It can be an in-line - * function or the name of a function. + * @param {function} [callback=null] - The function to call back when the script has been included. It can be either the + * name of a function or an in-line definition. * @example Include a script file asynchronously. * // First file: scriptA.js * print("This is script A"); @@ -370,14 +409,18 @@ 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 system model such as + * "sppUi". */ 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); @@ -390,7 +433,7 @@ public: /**jsdoc * Calls a function repeatedly, at a set interval. * @function Script.setInterval - * @param {function} function - The function to call. This 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. This can be used by {@link Script.clearInterval}. * @example Print a message every second. @@ -403,7 +446,7 @@ public: /**jsdoc * Calls a function once, after a delay. * @function Script.setTimeout - * @param {function} function - The function to call. This 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. This can be used by {@link Script.clearTimeout}. * @example Print a message once, after a second. @@ -447,8 +490,16 @@ public: Q_INVOKABLE void clearTimeout(QObject* timer) { stopTimer(reinterpret_cast(timer)); } /**jsdoc + * Prints a message to the program log. + *

Alternatively, you can use {@link print}, {@link console.log}, or one of the other {@link console} methods.

* @function Script.print - * @param {string} message + * @param {string} message - The message to print. + */ + /**jsdoc + * Prints a message to the program log. + *

This is an alias of {@link Script.print}.

+ * @function print + * @param {string} message - The message to print. */ Q_INVOKABLE void print(const QString& message); @@ -467,20 +518,25 @@ public: 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; @@ -488,9 +544,10 @@ public: // Entity Script Related methods /**jsdoc + * Checks whether an entity has an entity script running. * @function Script.isEntityScriptRunning - * @param {Uuid} entityID - * @returns {boolean} + * @param {Uuid} entityID - The ID of the entity. + * @returns {boolean} true if the entity has an entity script running, false if it doesn't. */ Q_INVOKABLE bool isEntityScriptRunning(const EntityItemID& entityID) { QReadLocker locker { &_entityScriptsLock }; @@ -524,34 +581,41 @@ public: Q_INVOKABLE void unloadAllEntityScripts(); /**jsdoc + * Calls a method in an entity script. * @function Script.callEntityScriptMethod - * @param {Uuid} entityID - * @param {string} methodName - * @param {string[]} [parameters=[]] - * @param {Uuid} [remoteCallerID=Uuid.NULL] + * @param {Uuid} entityID - The ID of the entity running the entity script. + * @param {string} methodName - The name of the method to call. + * @param {string[]} [parameters=[]] - The parameters to call the specified method with. + * @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 {string} methodName - * @param {PointerEvent} event + * @param {Uuid} entityID - Entity ID. + * @param {string} methodName - Method name. + * @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 {string} methodName - * @param {Uuid} otherID - * @param {Collision} collision + * @param {Uuid} entityID - Entity ID. + * @param {string} methodName - Method name. + * @param {Uuid} otherID - Other entity ID. + * @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(); } @@ -625,15 +689,17 @@ 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); @@ -685,38 +751,44 @@ signals: 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} scriptName + * @param {string} message - The message. + * @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} scriptName + * @param {string} message - The error message. + * @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} scriptName + * @param {string} message - The warning message. + * @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} scriptName + * @param {string} message - The information message. + * @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} */ @@ -731,21 +803,24 @@ signals: /**jsdoc * @function Script.loadScript - * @param {string} scriptName - * @param {boolean} isUserLoaded + * @param {string} scriptName - Script name. + * @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 {boolean} isUserLoaded + * @param {string} scriptName - Script name. + * @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} */ @@ -761,9 +836,28 @@ signals: void entityScriptDetailsUpdated(); /**jsdoc + * Triggered when the script starts for the user. See also, {@link Entities.preload}. + *
Available in:Client Entity ScriptsServer Entity Scripts
* @function Script.entityScriptPreloadFinished - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the entity that the script is running in. * @returns {Signal} + * @example Get the ID of the entity that a client entity script is running in. + * 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); diff --git a/libraries/shared/src/BaseScriptEngine.h b/libraries/shared/src/BaseScriptEngine.h index 6baa5d3c35..b750c20028 100644 --- a/libraries/shared/src/BaseScriptEngine.h +++ b/libraries/shared/src/BaseScriptEngine.h @@ -33,10 +33,11 @@ public: /**jsdoc * @function Script.lintScript - * @param {string} sourceCode - * @param {string} fileName - * @param {number} [lineNumber=1] - * @returns {object} + * @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); @@ -80,9 +81,15 @@ signals: // Script.signalHandlerException is exposed by QScriptEngine. /**jsdoc + * Triggered when a script generates an unhandled exception. * @function Script.unhandledException - * @param {object} exception + * @param {object} exception - The details of the exception. * @returns {Signal} + * @example Report the details of an unhandled exception. + * 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); From 5227b35c6b96295e4655ae1182872c85c7b3cbbc Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 21 May 2019 10:16:01 +1200 Subject: [PATCH 5/5] Revise changes --- libraries/script-engine/src/ScriptEngine.h | 32 +++++++++++----------- libraries/shared/src/BaseScriptEngine.h | 2 +- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index c6b1135fc6..e58609f01d 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -196,8 +196,8 @@ public: /**jsdoc * @function Script.registerGetterSetter * @param {string} name - Name. - * @param {object} getter - Getter. - * @param {object} setter - Setter. + * @param {function} getter - Getter. + * @param {function} setter - Setter. * @param {string} [parent=""] - Parent. * @deprecated This function is deprecated and will be removed. */ @@ -208,7 +208,7 @@ public: /**jsdoc * @function Script.registerFunction * @param {string} name - Name. - * @param {object} function - Function. + * @param {function} function - Function. * @param {number} [numArguments=-1] - Number of arguments. * @deprecated This function is deprecated and will be removed. */ @@ -219,7 +219,7 @@ public: * @function Script.registerFunction * @param {string} parent - Parent. * @param {string} name - Name. - * @param {object} function - Function. + * @param {function} function - Function. * @param {number} [numArguments=-1] - Number of arguments. * @deprecated This function is deprecated and will be removed. */ @@ -286,20 +286,20 @@ public: /**jsdoc * Checks whether the application was compiled as a debug build. * @function Script.isDebugMode - * @returns {boolean} true if the software was compiled as a debug build, false if it was + * @returns {boolean} true if the application was compiled as a debug build, false if it was * compiled as a release build. */ Q_INVOKABLE bool isDebugMode() const; /**jsdoc - * Checks whether the script content is a client entity script. + * Checks whether the script is running as a client entity script. * @function Script.isEntityClientScript * @returns {boolean} true if the script is running as a client entity script, false if it isn't. */ Q_INVOKABLE bool isEntityClientScript() const { return _context == ENTITY_CLIENT_SCRIPT; } /**jsdoc - * Checks whether the script context is a server entity script. + * Checks whether the script is running as a server entity script. * @function Script.isEntityServerScript * @returns {boolean} true if the script is running as a server entity script, false if it isn't. */ @@ -317,7 +317,7 @@ public: // NOTE - these are intended to be public interfaces available to scripts /**jsdoc - * Adds a function to the list of functions called upon the occurrence of an entity event on a particular entity. + * Adds a function to the list of functions called when an entity event occurs on a particular entity. * @function Script.addEventHandler * @param {Uuid} entityID - The ID of the entity. * @param {Script.EntityEvent} eventName - The name of the entity event. @@ -340,7 +340,7 @@ public: Q_INVOKABLE void addEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler); /**jsdoc - * Removes a function from the list of functions called upon the occurrence of an entity event on a particular entity. + * Removes a function from the list of functions called when an entity event occurs on a particular entity. * @function Script.removeEventHandler * @param {Uuid} entityID - The ID of the entity. * @param {Script.EntityEvent} eventName - The name of the entity event. @@ -412,7 +412,7 @@ public: * 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 - The module to use. May be a JavaScript file or the name of system model such as + * @param {string} module - The module to use. May be a JavaScript file or the name of a system module such as * "sppUi". */ Q_INVOKABLE QScriptValue require(const QString& moduleId); @@ -435,7 +435,7 @@ public: * @function Script.setInterval * @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. This can be used by {@link Script.clearInterval}. + * @returns {object} A handle to the interval timer. This can be used in {@link Script.clearInterval}. * @example Print a message every second. * Script.setInterval(function () { * print("Interval timer fired"); @@ -448,7 +448,7 @@ public: * @function Script.setTimeout * @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. This can be used by {@link Script.clearTimeout}. + * @returns {object} A handle to the timeout timer. This can be used in {@link Script.clearTimeout}. * @example Print a message once, after a second. * Script.setTimeout(function () { * print("Timeout timer fired"); @@ -559,7 +559,7 @@ public: /**jsdoc * @function Script.loadEntityScript - * @param {Uuid} entityID - Entity IUD. + * @param {Uuid} entityID - Entity ID. * @param {string} script - Script. * @param {boolean} forceRedownload - Force re-download. * @deprecated This function is deprecated and will be removed. @@ -669,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. @@ -867,7 +867,7 @@ protected: /**jsdoc * @function Script.executeOnScriptThread - * @param {object} function - Function. + * @param {function} function - Function. * @param {ConnectionType} [type=2] - Connection type. * @deprecated This function is deprecated and will be removed. */ @@ -904,7 +904,7 @@ protected: * @param {Uuid} entityID - Entity ID. * @param {string} scriptOrURL - Path. * @param {string} contents - Contents. - * @param {boolean} isURL - Is URL. + * @param {boolean} isURL - Is a URL. * @param {boolean} success - Success. * @param {string} status - Status. * @deprecated This function is deprecated and will be removed. diff --git a/libraries/shared/src/BaseScriptEngine.h b/libraries/shared/src/BaseScriptEngine.h index b750c20028..443c7b0500 100644 --- a/libraries/shared/src/BaseScriptEngine.h +++ b/libraries/shared/src/BaseScriptEngine.h @@ -44,7 +44,7 @@ public: /**jsdoc * @function Script.makeError * @param {object} [other] - Other. - * @param {string} [type="Error"] - Errorl + * @param {string} [type="Error"] - Error. * @returns {object} Object. * @deprecated This function is deprecated and will be removed. */