diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index d738b13ecc..7300f52f9b 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -351,8 +351,10 @@ public: Q_INVOKABLE void removeEventHandler(const EntityItemID& entityID, const QString& eventName, QScriptValue handler); /**jsdoc - * Starts running another script in Interface. - *
Available in:Interface ScriptsAvatar Scripts
+ * Starts running another script in Interface, if it isn't already running. The script is not automatically loaded next + * time Interface starts. + *

Supported Script Types: Interface Scripts • Avatar Scripts

+ *

See also, {@link ScriptDiscoveryService.loadScript}.

* @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. @@ -754,8 +756,8 @@ 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}. + * Triggered when the script prints a message to the program log via {@link print}, {@link Script.print}, + * {@link console.log}, or {@link console.debug}. * @function Script.printedMessage * @param {string} message - The message. * @param {string} scriptName - The name of the script that generated the message. @@ -764,7 +766,7 @@ signals: void printedMessage(const QString& message, const QString& scriptName); /**jsdoc - * Triggered when a script generates an error or {@link console.error} is called. + * Triggered when the script generates an error or {@link console.error} is called. * @function Script.errorMessage * @param {string} message - The error message. * @param {string} scriptName - The name of the script that generated the error message. @@ -773,7 +775,7 @@ signals: void errorMessage(const QString& message, const QString& scriptName); /**jsdoc - * Triggered when a script generates a warning or {@link console.warn} is called. + * Triggered when the script generates a warning or {@link console.warn} is called. * @function Script.warningMessage * @param {string} message - The warning message. * @param {string} scriptName - The name of the script that generated the warning message. @@ -782,7 +784,7 @@ signals: void warningMessage(const QString& message, const QString& scriptName); /**jsdoc - * Triggered when a script generates an information message or {@link console.info} is called. + * Triggered when the script generates an information message or {@link console.info} is called. * @function Script.infoMessage * @param {string} message - The information message. * @param {string} scriptName - The name of the script that generated the information message. @@ -845,8 +847,9 @@ signals: * @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 () { + * var entityScript = function () { * this.entityID = Uuid.NULL; + * }; * * Script.entityScriptPreloadFinished.connect(function (entityID) { * this.entityID = entityID; diff --git a/libraries/script-engine/src/ScriptEngines.cpp b/libraries/script-engine/src/ScriptEngines.cpp index 69455294d6..508a26302e 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 == "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 == "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..484ccd8932 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 entity 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: diff --git a/libraries/script-engine/src/ScriptsModel.h b/libraries/script-engine/src/ScriptsModel.h index adfb15affc..bd6c9687c1 100644 --- a/libraries/script-engine/src/ScriptsModel.h +++ b/libraries/script-engine/src/ScriptsModel.h @@ -64,14 +64,60 @@ public: }; /**jsdoc - *

Provided as a property of {@link ScriptDiscoveryService}.

- *

Has properties and functions below in addition to those of - * http://doc.qt.io/qt-5/qabstractitemmodel.html.

+ * Information on the scripts that are in the default scripts directory of the Interface installation. This is provided as a + * property of {@link ScriptDiscoveryService}. + * + *

The information provided reflects the subdirectory structure. Methods and signals are per QT's + * QAbstractItemModel class, with the following details:

+ * + * * @class ScriptsModel + + * @hideconstructor * * @hifi-interface * @hifi-client-entity * @hifi-avatar + * + * @example List the first 2 levels of the scripts directory. + * var MAX_DIRECTORY_LEVEL = 1; + * var DISPLAY_ROLE = 0; + * var PATH_ROLE = 256; + * + * function printDirectory(parentIndex, directoryLevel, indent) { + * var numRows = ScriptDiscoveryService.scriptsModel.rowCount(parentIndex); + * for (var i = 0; i < numRows; i++) { + * var rowIndex = ScriptDiscoveryService.scriptsModel.index(i, 0, parentIndex); + * + * var name = ScriptDiscoveryService.scriptsModel.data(rowIndex, DISPLAY_ROLE); + * var hasChildren = ScriptDiscoveryService.scriptsModel.hasChildren(rowIndex); + * var path = hasChildren ? "" : ScriptDiscoveryService.scriptsModel.data(rowIndex, PATH_ROLE); + * + * print(indent + "- " + name + (hasChildren ? "" : " - " + path)); + * + * if (hasChildren && directoryLevel < MAX_DIRECTORY_LEVEL) { + * printDirectory(rowIndex, directoryLevel + 1, indent + " "); + * } + * } + * } + * + * print("Scripts:"); + * printDirectory(null, 0, ""); // null index for the root directory. */ class ScriptsModel : public QAbstractItemModel { Q_OBJECT @@ -79,56 +125,25 @@ public: ScriptsModel(QObject* parent = NULL); ~ScriptsModel(); - /**jsdoc - * @function ScriptsModel.index - * @param {number} row - * @param {number} column - * @param {QModelIndex} parent - * @returns {QModelIndex} - */ + // No JSDoc because the particulars of the parent class is provided in the @class description. QModelIndex index(int row, int column, const QModelIndex& parent) const override; - /**jsdoc - * @function ScriptsModel.parent - * @param {QModelIndex} child - * @returns {QModelIndex} - */ + // No JSDoc because the particulars of the parent class is provided in the @class description. QModelIndex parent(const QModelIndex& child) const override; - /**jsdoc - * @function ScriptsModel.data - * @param {QModelIndex} index - * @param {number} [role=0] - * returns {string} - */ + // No JSDoc because the particulars of the parent class is provided in the @class description. QVariant data(const QModelIndex& index, int role = Qt::DisplayRole) const override; - /**jsdoc - * @function ScriptsModel.rowCount - * @param {QmodelIndex} [parent=null] - * @returns {number} - */ + // No JSDoc because the particulars of the parent class is provided in the @class description. int rowCount(const QModelIndex& parent = QModelIndex()) const override; - /**jsdoc - * @function ScriptsModel.columnCount - * @param {QmodelIndex} [parent=null] - * @returns {number} - */ + // No JSDoc because the particulars of the parent class is provided in the @class description. int columnCount(const QModelIndex& parent = QModelIndex()) const override; - /**jsdoc - * @function ScriptsModel.getTreeNodeFromIndex - * @param {QmodelIndex} index - * @returns {TreeNodeBase} - */ + // Not exposed in the API because no conversion between TreeNodeBase and QScriptValue is provided. TreeNodeBase* getTreeNodeFromIndex(const QModelIndex& index) const; - /**jsdoc - * @function ScriptsModel.getFolderNodes - * @param {TreeNodeFolder} parent - * @returns {TreeNodeBase[]} - */ + // Not exposed in the API because no conversion between TreeNodeBase and QScriptValue is provided. QList getFolderNodes(TreeNodeFolder* parent) const; enum Role { @@ -136,9 +151,30 @@ public: }; protected slots: + + /**jsdoc + * @function ScriptsModel.updateScriptsLocation + * @param {string} newPath - New path. + * @deprecated This method is deprecated and will be removed from the API. + */ void updateScriptsLocation(const QString& newPath); + + /**jsdoc + * @function ScriptsModel.downloadFinished + * @deprecated This method is deprecated and will be removed from the API. + */ void downloadFinished(); + + /**jsdoc + * @function ScriptsModel.reloadLocalFiles + * @deprecated This method is deprecated and will be removed from the API. + */ void reloadLocalFiles(); + + /**jsdoc + * @function ScriptsModel.reloadDefaultFiles + * @deprecated This method is deprecated and will be removed from the API. + */ void reloadDefaultFiles(); protected: diff --git a/libraries/script-engine/src/ScriptsModelFilter.h b/libraries/script-engine/src/ScriptsModelFilter.h index 81ae4c1226..eb7495e7d4 100644 --- a/libraries/script-engine/src/ScriptsModelFilter.h +++ b/libraries/script-engine/src/ScriptsModelFilter.h @@ -16,14 +16,60 @@ #include /**jsdoc - *

Provided as a property of {@link ScriptDiscoveryService}.

- *

Has properties and functions per - * http://doc.qt.io/qt-5/qsortfilterproxymodel.html.

+ * Sorted and filtered information on the scripts that are in the default scripts directory of the Interface installation. This + * is provided as a property of {@link ScriptDiscoveryService}. + * + *

The information provided reflects the subdirectory structure. Properties, methods, and signals are per QT's + * QSortFilterProxyModel class, with the following details:

+ *
    + *
  • The rows are sorted per directory and file names.
    • + *
  • A single column of data: columnCount(index) returns 1.
    • + *
  • Data is provided for the following roles: + * + * + * + * + * + * + * + * + *
    RoleValueDescription
    Display0The directory or script file name.
    Path256The path and filename of the data item if it is a script, + * undefined if it is a directory.
    + *
    • + *
  • Use null for the root directory's index.
    • + *
+ * * @class ScriptsModelFilter + * @hideconstructor * * @hifi-interface * @hifi-client-entity * @hifi-avatar + * + * @example List all scripts that include "edit" in their name. + * var DISPLAY_ROLE = 0; + * var PATH_ROLE = 256; + * + * function printDirectory(parentIndex, directoryLevel, indent) { + * var numRows = ScriptDiscoveryService.scriptsModelFilter.rowCount(parentIndex); + * for (var i = 0; i < numRows; i++) { + * var rowIndex = ScriptDiscoveryService.scriptsModelFilter.index(i, 0, parentIndex); + * + * var name = ScriptDiscoveryService.scriptsModelFilter.data(rowIndex, DISPLAY_ROLE); + * var hasChildren = ScriptDiscoveryService.scriptsModelFilter.hasChildren(rowIndex); + * var path = hasChildren ? "" : ScriptDiscoveryService.scriptsModelFilter.data(rowIndex, PATH_ROLE); + * + * print(indent + "- " + name + (hasChildren ? "" : " - " + path)); + * + * if (hasChildren) { + * printDirectory(rowIndex, directoryLevel + 1, indent + " "); + * } + * } + * } + * + * ScriptDiscoveryService.scriptsModelFilter.filterRegExp = new RegExp("^.*edit.*$", "i"); // Set the filter. + * print("Edit scripts:"); + * printDirectory(null, 0, ""); // null index for the root directory. */ class ScriptsModelFilter : public QSortFilterProxyModel { Q_OBJECT diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl index 451ed4d01a..2a5e863d6d 100644 --- a/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl +++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl @@ -92,7 +92,13 @@ - + + + + +

Example 1? 's':'' ?>

+ +

Description