ScriptDiscoveryService API JSDoc

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 - <code>"script"</code> or <code>"folder"</code>.
+ *     <p class="important">Deprecated: This property is deprecated and will be removed. It currently always has the value, 
+ *     <code>"script"</code>.</p>
+ * @property {ScriptDiscoveryService.PublicScript[]} [children] - Only present if <code>type</code> is <code>"folder"</code>.
+ *     <p class="important">Deprecated: This property is deprecated and will be removed. It currently is never present.
+ * @property {string} [url] - The full URL of the script &mdash; including the <code>"file:///"</code> scheme at the start.
+ *     <p>Only present if <code>type</code> is <code>"script"</code>.</p>
+ */
 QVariantList getPublicChildNodes(TreeNodeFolder* parent) {
     QVariantList result;
     QList<TreeNodeBase*> 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<TreeNodeBase*> 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 - <code>true</code> if the script is a local file (i.e., the scheme is "file"), <code>false</code> 
+ *     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 &mdash; excluding the scheme if a local file.
+ * @property {string} url - The full URL of the script &mdash; including the scheme if a local file.
+ */
 QVariantList ScriptEngines::getRunning() {
     QVariantList result;
     auto runningScripts = getRunningScripts();

libraries/script-engine/src/ScriptEngines.h

@@ -28,18 +28,26 @@
 class ScriptEngine;
 
 /**jsdoc
+ * The <code>ScriptDiscoveryService</code> 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} debugScriptUrl="" - The path and name of a script to debug using the "API Debugger" developer tool 
- * @property {string} defaultScriptsPath
+ *     (currentAPI.js). If set, the API Debugger dialog displays the objects and values exposed by the script using 
- * @property {ScriptsModel} scriptsModel
+ *     {@link Script.registerValue} and similar.
- * @property {ScriptsModelFilter} scriptsModelFilter
+ * @property {string} defaultScriptsPath - The path where the default scripts are located in the Interface installation. 
+ *     <em>Read-only.</em>
+ * @property {ScriptsModel} scriptsModel - Information on the scripts that are in the default scripts directory of the 
+ *     Interface installation.
+ *     <em>Read-only.</em>
+ * @property {ScriptsModelFilter} scriptsModelFilter - Sorted and filtered information on the scripts that are in the default 
+ *     scripts directory of the Interface installation.
+ *     <em>Read-only.</em>
  */
-
 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.
+     * <p>This is a synonym for calling {@link ScriptDiscoveryService.loadScript|loadScript} with just the script URL.</p>
+     * <p class="availableIn"><strong>Supported Script Types:</strong> Interface Scripts &bull; Avatar Scripts</p>
+     * <p>See also, {@link Script.load}.</p>
      * @function ScriptDiscoveryService.loadOneScript
-     * @param {string} filename
+     * @param {string} url - The path and name of the script. If a local file, including the <code>"file:///"</code> scheme is 
+     *     optional.
      */
     Q_INVOKABLE void loadOneScript(const QString& scriptFilename);
 
     /**jsdoc
+     * Starts running an Interface script, if it isn't already running.
+     * <p class="availableIn"><strong>Supported Script Types:</strong> Interface Scripts &bull; Avatar Scripts</p>
+     * <p>See also, {@link Script.load}.</p>
      * @function ScriptDiscoveryService.loadScript
-     * @param {string} [filename=""]
+     * @param {string} [url=""] - The path and name of the script. If a local file, including the <code>"file:///"</code> 
-     * @param {boolean} [isUserLoaded=true]
+     *     scheme is optional.
-     * @param {boolean} [loadScriptFromEditor=false]
+     * @param {boolean} [isUserLoaded=true] - <code>true</code> if the user specifically loaded it, <code>false</code> if not 
-     * @param {boolean} [activateMainWindow=false]
+     *     (e.g., a script loaded it). If <code>false</code>, the script is not automatically loaded next time Interface starts.
-     * @param {boolean} [reload=false]
+     * @param {boolean} [loadScriptFromEditor=false] - <em>Not used.</em>
-     * @param {boolean} [quitWhenFinished=false]
+     * @param {boolean} [activateMainWindow=false] - <em>Not used.</em>
-     * @returns {boolean}
+     * @param {boolean} [reload=false] - <code>true</code> to redownload the script, <code>false</code> to use the copy from 
+     *     the cache if available.
+     * @param {boolean} [quitWhenFinished=false] - <code>true</code> to close Interface when the script finishes, 
+     *     <code>false</code> to not close Interface.
+     * @returns {object} An empty object, <code>{}</code>.
      */
     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 {string} url - The path and name of the script. If a local file, including the <code>"file:///"</code> scheme is 
-     * @param {boolean} [restart=false]
+     *     optional.
-     * @returns {boolean}
+     * @param {boolean} [restart=false] -  <code>true</code> to redownload and restart the script, <code>false</code> to stop 
+     *     it.
+     * @returns {boolean} <code>true</code> if the script was successfully stopped or restarted, <code>false</code> 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] - <code>true</code> to restart the scripts, <code>false</code> 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 <caption>Report all running scripts.</caption>
+     * 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 <caption>Report when the number of running scripts changes.</caption>
+     * 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} url - The path and name of the script that could not be loaded.
-     * @param {string} error
+     * @param {string} error - <code>""</code> 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} message - The message.
-     * @param {string} engineName
+     * @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} message - The error message.
-     * @param {string} engineName
+     * @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} message - The warning message.
-     * @param {string} engineName
+     * @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} message - The information message.
-     * @param {string} engineName
+     * @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} message - Message.
-     * @param {string} scriptName
+     * @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} message - Message.
-     * @param {string} scriptName
+     * @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} message - Message.
-     * @param {string} scriptName
+     * @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} message - Message.
-     * @param {string} scriptName
+     * @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 {string} scriptName - Script name.
-     * @param {object} engine
+     * @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: