Mirrors/overte-JulianGro
3
0
Fork 0
mirror of https://github.com/JulianGro/overte.git synced 2025-04-14 09:06:32 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Polish existing Script JSDoc

Browse source
This commit is contained in:
David Rowe 2019-05-10 08:33:03 +12:00
parent 0e478de1a2
commit d196e35701
1 changed files with 54 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
libraries/script-engine/src/ScriptEngine.h
View file

@ -100,6 +100,8 @@ public:
};
/**jsdoc
* The <code>Script</code> API provides facilities for working with scripts.
*
* @namespace Script
*
* @hifi-interface
@ -150,9 +152,18 @@ public:
QList<EntityItemID> getListOfEntityScriptIDs();
/**jsdoc
* Stop the current script.
* Stops and unloads the current script.
* @function Script.stop
* @param {boolean} [marshal=false]
* @param {boolean} [marshal=false] - Marshal.
* <p class="important">Deprecated: This parameter is deprecated and will be removed.</p>
* @example <caption>Stop a script after 5s.</caption>
* Script.setInterval(function () {
* print("Hello");
* }, 1000);
*
* Script.setTimeout(function () {
* Script.stop(true);
* }, 5000);
*/
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// NOTE - this is intended to be a public interface for Agent scripts, and local scripts, but not for EntityScripts
@ -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.
* <p><strong>Note:</strong> Only works for Interface and avatar scripts.</p>
* @function Script.load
* @param {string} filename - The URL of the script to load. Can be relative to the current script.
* @param {string} filename - The URL of the script to load. This can be relative to the current script's URL.
* @example <caption>Load a script from another script.</caption>
* // First file: scriptA.js
* print("This is script A");
@ -303,7 +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 <caption>Include a script file asynchronously.</caption>
* // 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 <caption>Print a message every second.</caption>
* Script.setInterval(function () {
* print("Timer fired");
* print("Interval timer fired");
* }, 1000);
*/
Q_INVOKABLE QObject* setInterval(const QScriptValue& function, int intervalMS);
/**jsdoc
* Call a function after a delay.
* Calls a function once, after a delay.
* @function Script.setTimeout
* @param {function} function - The function to call. Can be an in-line function or the name of a function.
* @param {function} function - The function to call. This can be 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 <caption>Print a message after a second.</caption>
* @returns {object} A handle to the timeout timer. This can be used by {@link Script.clearTimeout}.
* @example <caption>Print a message once, after a second.</caption>
* Script.setTimeout(function () {
* print("Timer fired");
* print("Timeout timer fired");
* }, 1000);
*/
Q_INVOKABLE QObject* setTimeout(const QScriptValue& function, int timeoutMS);
/**jsdoc
* Stop an interval timer set by {@link Script.setInterval|setInterval}.
* Stops an interval timer set by {@link Script.setInterval|setInterval}.
* @function Script.clearInterval
* @param {object} timer - The interval timer to clear.
* @param {object} timer - The interval timer to stop.
* @example <caption>Stop an interval timer.</caption>
* // Print a message every second.
* var timer = Script.setInterval(function () {
* print("Timer fired");
* print("Interval timer fired");
* }, 1000);
*
* // Stop the timer after 10 seconds.
* Script.setTimeout(function () {
* print("Stop timer");
* print("Stop interval timer");
* Script.clearInterval(timer);
* }, 10000);
*/
Q_INVOKABLE void clearInterval(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); }
/**jsdoc
* Clear a timeout timer set by {@link Script.setTimeout|setTimeout}.
* Stops a timeout timer set by {@link Script.setTimeout|setTimeout}.
* @function Script.clearTimeout
* @param {object} timer - The timeout timer to clear.
* @param {object} timer - The timeout timer to stop.
* @example <caption>Stop a timeout timer.</caption>
* // Print a message after two seconds.
* var timer = Script.setTimeout(function () {
@ -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 <caption>Report the directory and filename of the running script.</caption>
* print(Script.resolvePath(""));
* @example <caption>Report the directory of the running script.</caption>
* print(Script.resolvePath("."));
* @example <caption>Report the path to a file located relative to the running script.</caption>
* print(Script.resolvePath("../assets/sounds/hello.wav"));
*/
Q_INVOKABLE QUrl resolvePath(const QString& path) const;
@ -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 <caption>Report script update intervals.</caption>
* Script.update.connect(function (deltaTime) {
* print("Update: " + deltaTime);
* });
*/
void update(float deltaTime);
/**jsdoc
* Triggered when the script is ending.
* Triggered when the script is stopping.
* @function Script.scriptEnding
* @returns {Signal}
* @example <caption>Connect to the <code>scriptEnding</code> signal.</caption>
* @example <caption>Report when a script is stopping.</caption>
* print("Script started");
*
* Script.scriptEnding.connect(function () {