Merge pull request #16567 from ctrlaltdavid/DOC-240

DOC-240: console JSDoc

libraries/script-engine/src/ConsoleScriptingInterface.h

@@ -26,25 +26,190 @@
 #include <QtCore/QHash>
 #include <QtScript/QScriptable>
 
+/**jsdoc
+ * The <code>console</code> 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.
+     * <p>If a {@link console.group} is in effect, the message is indented by an amount proportional to the group level.</p>
+     * @function console.log
+     * @param {...*} [message] - The message values to log.
+     * @example <caption>Log some values.</caption>
+     * 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.
+     * <p>Note: Script execution continues whether or not the test condition fails.</p>
+     * @function console.assert
+     * @param {boolean} assertion - The test condition value.
+     * @param {...*} [message] - The message values to log if the assertion evaluates to <code>false</code>.
+     * @example <caption>Demonstrate assertion behavior.</caption>
+     * 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 <caption>Nested groups.</caption>
+     * 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 <caption>Time some processing.</caption>
+     * 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 &gt; Scripting &gt; Script Log debug window.
+     * @function console.clear
+     */
     void clear();
 
 private:    

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.
+     * <p>Alternatively, you can use {@link Script.print} or one of the {@link console} API methods.</p>
+     * @function print
+     * @param {...*} [message] - The message values to print.
+     */
     globalObject().setProperty("print", newFunction(debugPrint));
 
     QScriptValue audioEffectOptionsConstructorValue = newFunction(AudioEffectOptions::constructor);

libraries/script-engine/src/ScriptEngine.h

@@ -499,17 +499,11 @@ public:
     Q_INVOKABLE void clearTimeout(QObject* timer) { stopTimer(reinterpret_cast<QTimer*>(timer)); }
 
     /**jsdoc
-     * Prints a message to the program log.
+     * Prints a message to the program log and emits {@link Script.printedMessage}.
-     * <p>Alternatively, you can use {@link print}, {@link console.log}, or one of the other {@link console} methods.</p>
+     * <p>Alternatively, you can use {@link print} or one of the {@link console} API methods.</p>
      * @function Script.print
      * @param {string} message - The message to print.
      */
-    /**jsdoc
-     * Prints a message to the program log.
-     * <p>This is an alias of {@link Script.print}.</p>
-     * @function print
-     * @param {string} message - The message to print.
-     */
     Q_INVOKABLE void print(const QString& message);
 
     /**jsdoc
@@ -763,7 +757,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 +767,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.