From e1e74a2c3486ffc4e24b4d1684ca45a5afef174d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 27 Aug 2019 08:44:51 +1200 Subject: [PATCH] ScriptDiscoveryService API JSDoc --- libraries/script-engine/src/ScriptEngines.cpp | 28 +++ libraries/script-engine/src/ScriptEngines.h | 160 +++++++++++++----- 2 files changed, 143 insertions(+), 45 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngines.cpp b/libraries/script-engine/src/ScriptEngines.cpp index 69455294d6..78d4dfab06 100644 --- a/libraries/script-engine/src/ScriptEngines.cpp +++ b/libraries/script-engine/src/ScriptEngines.cpp @@ -209,6 +209,18 @@ void ScriptEngines::shutdownScripting() { qCDebug(scriptengine) << "DONE Stopping all scripts...."; } +/**jsdoc + * Information on a public script, i.e., a script that's included in the Interface installation. + * @typedef {object} ScriptDiscoveryService.PublicScript + * @property {string} name - The script's file name. + * @property {string} type - "script" or "folder". + *

Deprecated: This property is deprecated and will be removed. It currently always has the value, + * "script".

+ * @property {ScriptDiscoveryService.PublicScript[]} [children] - Only present if type is "folder". + *

Deprecated: This property is deprecated and will be removed. It currently is never present. + * @property {string} [url] - The full URL of the script — including the "file:///" scheme at the start. + *

Only present if type is "script".

+ */ QVariantList getPublicChildNodes(TreeNodeFolder* parent) { QVariantList result; QList treeNodes = getScriptsModel().getFolderNodes(parent); @@ -240,6 +252,13 @@ QVariantList ScriptEngines::getPublic() { return getPublicChildNodes(NULL); } +/**jsdoc + * Information on a local script. + * @typedef {object} ScriptDiscoveryService.LocalScript + * @property {string} name - The script's file name. + * @property {string} path - The script's path. + * @deprecated This type is deprecated and will be removed. + */ QVariantList ScriptEngines::getLocal() { QVariantList result; QList treeNodes = getScriptsModel().getFolderNodes(NULL); @@ -260,6 +279,15 @@ QVariantList ScriptEngines::getLocal() { return result; } +/**jsdoc + * Information on a running script. + * @typedef {object} ScriptDiscoveryService.RunningScript + * @property {boolean} local - true if the script is a local file (i.e., the scheme is "file"), false + * if it isn't (e.g., the scheme is "http"). + * @property {string} name - The script's file name. + * @property {string} path - The script's path and file name — excluding the scheme if a local file. + * @property {string} url - The full URL of the script — including the scheme if a local file. + */ QVariantList ScriptEngines::getRunning() { QVariantList result; auto runningScripts = getRunningScripts(); diff --git a/libraries/script-engine/src/ScriptEngines.h b/libraries/script-engine/src/ScriptEngines.h index de836a3e09..89501da88b 100644 --- a/libraries/script-engine/src/ScriptEngines.h +++ b/libraries/script-engine/src/ScriptEngines.h @@ -28,18 +28,26 @@ class ScriptEngine; /**jsdoc + * The ScriptDiscoveryService API provides facilities to work with Interface scripts. + * * @namespace ScriptDiscoveryService * * @hifi-interface - * @hifi-client-entity * @hifi-avatar + * @hifi-client-entity * - * @property {string} debugScriptUrl - * @property {string} defaultScriptsPath - * @property {ScriptsModel} scriptsModel - * @property {ScriptsModelFilter} scriptsModelFilter + * @property {string} debugScriptUrl="" - The path and name of a script to debug using the "API Debugger" developer tool + * (currentAPI.js). If set, the API Debugger dialog displays the objects and values exposed by the script using + * {@link Script.registerValue} and similar. + * @property {string} defaultScriptsPath - The path where the default scripts are located in the Interface installation. + * Read-only. + * @property {ScriptsModel} scriptsModel - Information on the scripts that are in the default scripts directory of the + * Interface installation. + * Read-only. + * @property {ScriptsModelFilter} scriptsModelFilter - Sorted and filtered information on the scripts that are in the default + * scripts directory of the Interface installation. + * Read-only. */ - class NativeScriptInitializers : public ScriptInitializerMixin { public: bool registerNativeScriptInitializer(NativeScriptInitializer initializer) override; @@ -77,61 +85,92 @@ public: QString getDefaultScriptsLocation() const; /**jsdoc + * Starts running an Interface script, if it isn't already running. The script is automatically loaded next time Interface + * starts. + *

This is a synonym for calling {@link ScriptDiscoveryService.loadScript|loadScript} with just the script URL.

+ *

Supported Script Types: Interface Scripts • Avatar Scripts

+ *

See also, {@link Script.load}.

* @function ScriptDiscoveryService.loadOneScript - * @param {string} filename + * @param {string} url - The path and name of the script. If a local file, including the "file:///" scheme is + * optional. */ Q_INVOKABLE void loadOneScript(const QString& scriptFilename); /**jsdoc + * Starts running an Interface script, if it isn't already running. + *

Supported Script Types: Interface Scripts • Avatar Scripts

+ *

See also, {@link Script.load}.

* @function ScriptDiscoveryService.loadScript - * @param {string} [filename=""] - * @param {boolean} [isUserLoaded=true] - * @param {boolean} [loadScriptFromEditor=false] - * @param {boolean} [activateMainWindow=false] - * @param {boolean} [reload=false] - * @param {boolean} [quitWhenFinished=false] - * @returns {boolean} + * @param {string} [url=""] - The path and name of the script. If a local file, including the "file:///" + * scheme is optional. + * @param {boolean} [isUserLoaded=true] - true if the user specifically loaded it, false if not + * (e.g., a script loaded it). If false, the script is not automatically loaded next time Interface starts. + * @param {boolean} [loadScriptFromEditor=false] - Not used. + * @param {boolean} [activateMainWindow=false] - Not used. + * @param {boolean} [reload=false] - true to redownload the script, false to use the copy from + * the cache if available. + * @param {boolean} [quitWhenFinished=false] - true to close Interface when the script finishes, + * false to not close Interface. + * @returns {object} An empty object, {}. */ Q_INVOKABLE ScriptEnginePointer loadScript(const QUrl& scriptFilename = QString(), bool isUserLoaded = true, bool loadScriptFromEditor = false, bool activateMainWindow = false, bool reload = false, bool quitWhenFinished = false); /**jsdoc + * Stops or restarts an Interface script. * @function ScriptDiscoveryService.stopScript - * @param {string} scriptHash - * @param {boolean} [restart=false] - * @returns {boolean} + * @param {string} url - The path and name of the script. If a local file, including the "file:///" scheme is + * optional. + * @param {boolean} [restart=false] - true to redownload and restart the script, false to stop + * it. + * @returns {boolean} true if the script was successfully stopped or restarted, false if it + * wasn't (e.g., the script couldn't be found). */ Q_INVOKABLE bool stopScript(const QString& scriptHash, bool restart = false); /**jsdoc - * @function ScriptDiscoveryService.reloadAllScripts - */ + * Restarts all Interface, avatar, and client scripts after clearing the scripts cache. + * @function ScriptDiscoveryService.reloadAllScripts + */ Q_INVOKABLE void reloadAllScripts(); /**jsdoc + * Stops or restarts all Interface scripts. The scripts cache is not cleared. If restarting, avatar and client entity + * scripts are also restarted. * @function ScriptDiscoveryService.stopAllScripts - * @param {boolean} [restart=false] + * @param {boolean} [restart=false] - true to restart the scripts, false to stop them. */ Q_INVOKABLE void stopAllScripts(bool restart = false); /**jsdoc + * Gets a list of all Interface scripts that are currently running. * @function ScriptDiscoveryService.getRunning - * @returns {object[]} + * @returns {ScriptDiscoveryService.RunningScript[]} All Interface scripts that are currently running. + * @example Report all running scripts. + * var runningScripts = ScriptDiscoveryService.getRunning(); + * print("Running scripts:"); + * for (var i = 0; i < runningScripts.length; i++) { + * print(JSON.stringify(runningScripts[i])); + * } */ Q_INVOKABLE QVariantList getRunning(); /**jsdoc + * Gets a list of all script files that are in the default scripts directory of the Interface installation. * @function ScriptDiscoveryService.getPublic - * @returns {object[]} + * @returns {ScriptDiscoveryService.PublicScript[]} All scripts in the "scripts" directory of the Interface + * installation. */ Q_INVOKABLE QVariantList getPublic(); /**jsdoc * @function ScriptDiscoveryService.getLocal - * @returns {object[]} + * @returns {ScriptDiscoveryService.LocalScript[]} Local scripts. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because there is no longer a notion of a "local" scripts folder where you would put your personal scripts. Q_INVOKABLE QVariantList getLocal(); // FIXME: Move to other Q_PROPERTY declarations. @@ -148,65 +187,82 @@ public: signals: /**jsdoc + * Triggered when the number of Interface scripts running changes. * @function ScriptDiscoveryService.scriptCountChanged * @returns {Signal} + * @example Report when the number of running scripts changes. + * ScriptDiscoveryService.scriptCountChanged.connect(function () { + * print("Scripts count changed: " + ScriptDiscoveryService.getRunning().length); + * }); */ void scriptCountChanged(); /**jsdoc + * Triggered when Interface, avatar, and client entity scripts are restarting as a result of + * {@link ScriptDiscoveryService.reloadAllScripts|reloadAllScripts} or + * {@link ScriptDiscoveryService.stopAllScripts|stopAllScripts}. * @function ScriptDiscoveryService.scriptsReloading * @returns {Signal} */ void scriptsReloading(); /**jsdoc + * Triggered when a script could not be loaded. * @function ScriptDiscoveryService.scriptLoadError - * @param {string} filename - * @param {string} error + * @param {string} url - The path and name of the script that could not be loaded. + * @param {string} error - "" always. * @returns {Signal} */ void scriptLoadError(const QString& filename, const QString& error); /**jsdoc + * Triggered when any script prints a message to the program log via {@link print}, {@link Script.print}, + * {@link console.log}, or {@link console.debug}. * @function ScriptDiscoveryService.printedMessage - * @param {string} message - * @param {string} engineName + * @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& engineName); /**jsdoc + * Triggered when any script generates an error or {@link console.error} is called. * @function ScriptDiscoveryService.errorMessage - * @param {string} message - * @param {string} engineName + * @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& engineName); /**jsdoc + * Triggered when any script generates a warning or {@link console.warn} is called. * @function ScriptDiscoveryService.warningMessage - * @param {string} message - * @param {string} engineName + * @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& engineName); /**jsdoc + * Triggered when any script generates an information message or {@link console.info} is called. * @function ScriptDiscoveryService.infoMessage - * @param {string} message - * @param {string} engineName + * @param {string} message - The information message. + * @param {string} scriptName - The name of the script that generated the informaton message. * @returns {Signal} */ void infoMessage(const QString& message, const QString& engineName); /**jsdoc * @function ScriptDiscoveryService.errorLoadingScript - * @param {string} url + * @param {string} url - URL. * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ + // Deprecated because never emitted. void errorLoadingScript(const QString& url); /**jsdoc + * Triggered when the Debug Window is cleared. * @function ScriptDiscoveryService.clearDebugWindow * @returns {Signal} */ @@ -216,50 +272,64 @@ public slots: /**jsdoc * @function ScriptDiscoveryService.onPrintedMessage - * @param {string} message - * @param {string} scriptName + * @param {string} message - Message. + * @param {string} scriptName - Script name. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. void onPrintedMessage(const QString& message, const QString& scriptName); /**jsdoc * @function ScriptDiscoveryService.onErrorMessage - * @param {string} message - * @param {string} scriptName + * @param {string} message - Message. + * @param {string} scriptName - Script name. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. void onErrorMessage(const QString& message, const QString& scriptName); /**jsdoc * @function ScriptDiscoveryService.onWarningMessage - * @param {string} message - * @param {string} scriptName + * @param {string} message - Message. + * @param {string} scriptName - Script name. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. void onWarningMessage(const QString& message, const QString& scriptName); /**jsdoc * @function ScriptDiscoveryService.onInfoMessage - * @param {string} message - * @param {string} scriptName + * @param {string} message - Message. + * @param {string} scriptName - Script name. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. void onInfoMessage(const QString& message, const QString& scriptName); /**jsdoc * @function ScriptDiscoveryService.onErrorLoadingScript - * @param {string} url + * @param {string} url - URL. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. And it isn't used. void onErrorLoadingScript(const QString& url); /**jsdoc * @function ScriptDiscoveryService.onClearDebugWindow + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because only use is to emit a signal. void onClearDebugWindow(); protected slots: /**jsdoc * @function ScriptDiscoveryService.onScriptFinished - * @param {string} filename - * @param {object} engine + * @param {string} scriptName - Script name. + * @param {object} engine - Engine. + * @deprecated This function is deprecated and will be removed. */ + // Deprecated because it wasn't intended to be in the API. void onScriptFinished(const QString& fileNameString, ScriptEnginePointer engine); protected: