From 7d2e818ab1422abaec06bc39bab4acfef221ad8a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 11 Dec 2019 07:41:37 +1300 Subject: [PATCH 1/3] console JSDoc --- .../src/ConsoleScriptingInterface.h | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) diff --git a/libraries/script-engine/src/ConsoleScriptingInterface.h b/libraries/script-engine/src/ConsoleScriptingInterface.h index deb0d126f9..7eec44d103 100644 --- a/libraries/script-engine/src/ConsoleScriptingInterface.h +++ b/libraries/script-engine/src/ConsoleScriptingInterface.h @@ -26,25 +26,190 @@ #include #include +/**jsdoc + * The console API provides program logging facilities. + * + * @namespace console + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * @hifi-server-entity + * @hifi-assignment-client + */ // Scriptable interface of "console" object. Used exclusively in the JavaScript API class ConsoleScriptingInterface : public QObject, protected QScriptable { Q_OBJECT public: + + /**jsdoc + * Logs an "INFO" message to the program log and triggers {@link Script.infoMessage}. + * The message logged is "INFO -" followed by the message values separated by spaces. + * @function console.info + * @param {...*} [message] - The message values to log. + */ static QScriptValue info(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs a message to the program log and triggers {@link Script.printedMessage}. + * The message logged is the message values separated by spaces. + *

If a {@link console.group} is in effect, the message is indented by an amount proportional to the group level.

+ * @function console.log + * @param {...*} [message] - The message values to log. + * @example Log some values. + * Script.printedMessage.connect(function (message, scriptName) { + * console.info("Console.log message:", "\"" + message + "\"", "in", "[" + scriptName + "]"); + * }); + * + * console.log("string", 7, true); + * + * // string 7 true + * // INFO - Console.log message: "string 7 true" in [console.js] + */ static QScriptValue log(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs a message to the program log and triggers {@link Script.printedMessage}. + * The message logged is the message values separated by spaces. + * @function console.debug + * @param {...*} [message] - The message values to log. + */ static QScriptValue debug(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs a "WARNING" message to the program log and triggers {@link Script.warningMessage}. + * The message logged is "WARNING - " followed by the message values separated by spaces. + * @function console.warn + * @param {...*} [message] - The message values to log. + */ static QScriptValue warn(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}. + * The message logged is "ERROR - " followed by the message values separated by spaces. + * @function console.error + * @param {...*} [message] - The message values to log. + */ static QScriptValue error(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * A synonym of {@link console.error}. + * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}. + * The message logged is "ERROR - " followed by the message values separated by spaces. + * @function console.exception + * @param {...*} [message] - The message values to log. + */ static QScriptValue exception(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}, if a test condition fails. + * The message logged is "ERROR - Assertion failed : " followed by the message values separated by spaces. + *

Note: Script execution continues whether or not the test condition fails.

+ * @function console.assert + * @param {boolean} assertion - The test condition value. + * @param {...*} [message] - The message values to log if the assertion evaluates to false. + * @example Demonstrate assertion behavior. + * Script.errorMessage.connect(function (message, scriptName) { + * console.info("Error message logged:", "\"" + message + "\"", "in", "[" + scriptName + "]"); + * }); + * + * console.assert(5 === 5, "5 equals 5.", "This assertion will succeed."); // No log output. + * console.assert(5 > 6, "5 is not greater than 6.", "This assertion will fail."); // Log output is generated. + * console.info("Script continues running."); + * + * // ERROR - Assertion failed : 5 is not greater than 6. This assertion will fail. + * // INFO - Error message logged: "Assertion failed : 5 is not greater than 6. This assertion will fail." in [console.js] + * // INFO - Script continues running. + */ + // Note: Is registered in the script engine as "assert" static QScriptValue assertion(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent + * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested. + * @function console.group + * @param {*} message - The message value to log. + * @example Nested groups. + * console.group("Group 1"); + * console.log("Sentence 1"); + * console.log("Sentence 2"); + * console.group("Group 2"); + * console.log("Sentence 3"); + * console.log("Sentence 4"); + * console.groupEnd(); + * console.log("Sentence 5"); + * console.groupEnd(); + * console.log("Sentence 6"); + * + * //Group 1 + * // Sentence 1 + * // Sentence 2 + * // Group 2 + * // Sentence 3 + * // Sentence 4 + * // Sentence 5 + * //Sentence 6 + */ static QScriptValue group(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Has the same behavior as {@link console.group}. + * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent + * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested. + * @function console.groupCollapsed + * @param {*} message - The message value to log. + */ static QScriptValue groupCollapsed(QScriptContext* context, QScriptEngine* engine); + + /**jsdoc + * Finishes a group of indented {@link console.log} messages. + * @function console.groupEnd + */ static QScriptValue groupEnd(QScriptContext* context, QScriptEngine* engine); public slots: + + /**jsdoc + * Starts a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has + * the timer name and "Timer started". + * @function console.time + * @param {string} name - The name of the timer. + * @example Time some processing. + * function sleep(milliseconds) { + * var start = new Date().getTime(); + * for (var i = 0; i < 1e7; i++) { + * if ((new Date().getTime() - start) > milliseconds) { + * break; + * } + * } + * } + * + * console.time("MyTimer"); + * sleep(1000); // Do some processing. + * console.timeEnd("MyTimer"); + * + * // MyTimer: Timer started + * // MyTimer: 1001ms */ void time(QString labelName); + + /**jsdoc + * Finishes a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has + * the timer name and the number of milliseconds since the timer was started. + * @function console.timeEnd + * @param {string} name - The name of the timer. + */ void timeEnd(QString labelName); + + /**jsdoc + * Logs the JavaScript call stack at the point of call to the program log. + * @function console.trace + */ void trace(); + + /**jsdoc + * Clears the Developer > Scripting > Script Log debug window. + * @function console.clear + */ void clear(); private: From 5caa21e5d9dd55aa1039f4640cd62fbb915059c1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 11 Dec 2019 07:42:40 +1300 Subject: [PATCH 2/3] Update Script JSDoc accordingly --- libraries/script-engine/src/ScriptEngine.h | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 94381ede02..404ac1ae41 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -499,8 +499,8 @@ 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.

+ * Prints a message to the program log and emits {@link Script.printedMessage}. + *

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

* @function Script.print * @param {string} message - The message to print. */ @@ -763,7 +763,8 @@ signals: /**jsdoc * Triggered when the script prints a message to the program log via {@link print}, {@link Script.print}, - * {@link console.log}, or {@link console.debug}. + * {@link console.log}, {@link console.debug}, {@link console.group}, {@link console.groupEnd}, {@link console.time}, or + * {@link console.timeEnd}. * @function Script.printedMessage * @param {string} message - The message. * @param {string} scriptName - The name of the script that generated the message. @@ -772,7 +773,8 @@ signals: void printedMessage(const QString& message, const QString& scriptName); /**jsdoc - * Triggered when the script generates an error or {@link console.error} is called. + * Triggered when the script generates an error, {@link console.error} or {@link console.exception} is called, or + * {@link console.assert} is called and fails. * @function Script.errorMessage * @param {string} message - The error message. * @param {string} scriptName - The name of the script that generated the error message. From bbd16d7544166ef4fb3fd51a49d3d807ed5e76d4 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 11 Dec 2019 07:42:58 +1300 Subject: [PATCH 3/3] Fix global print function's JSDoc --- libraries/script-engine/src/ScriptEngine.cpp | 7 +++++++ libraries/script-engine/src/ScriptEngine.h | 6 ------ 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp index 4cf4a9fc42..7e3f556c2d 100644 --- a/libraries/script-engine/src/ScriptEngine.cpp +++ b/libraries/script-engine/src/ScriptEngine.cpp @@ -731,6 +731,13 @@ void ScriptEngine::init() { QScriptValue webSocketConstructorValue = newFunction(WebSocketClass::constructor); globalObject().setProperty("WebSocket", webSocketConstructorValue); + /**jsdoc + * Prints a message to the program log and emits {@link Script.printedMessage}. + * The message logged is the message values separated by spaces. + *

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

+ * @function print + * @param {...*} [message] - The message values to print. + */ globalObject().setProperty("print", newFunction(debugPrint)); QScriptValue audioEffectOptionsConstructorValue = newFunction(AudioEffectOptions::constructor); diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 404ac1ae41..3891f60d92 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -504,12 +504,6 @@ public: * @function Script.print * @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); /**jsdoc