History

console JSDoc

David Rowe committed 6 years ago

Commit 7d2e8181 parent 6312a7c1 file · +165 −0Browse files

Showing the changes to libraries/script-engine/src/ConsoleScriptingInterface.h (1 of 1 file). Show all

Unified · Split

libraries/script-engine/src/ConsoleScriptingInterface.h+165−0
@@ -26,25 +26,190 @@ · 25 unmodified lines
2626 #include <QtCore/QHash>
2727 #include <QtScript/QScriptable>
2828
29+/**jsdoc
30+ * The <code>console</code> API provides program logging facilities.
31+ *
32+ * @namespace console
33+ *
34+ * @hifi-interface
35+ * @hifi-client-entity
36+ * @hifi-avatar
37+ * @hifi-server-entity
38+ * @hifi-assignment-client
39+ */
2940 // Scriptable interface of "console" object. Used exclusively in the JavaScript API
3041 class ConsoleScriptingInterface : public QObject, protected QScriptable {
3142 Q_OBJECT
3243 public:
44+
45+ /**jsdoc
46+ * Logs an "INFO" message to the program log and triggers {@link Script.infoMessage}.
47+ * The message logged is "INFO -" followed by the message values separated by spaces.
48+ * @function console.info
49+ * @param {...*} [message] - The message values to log.
50+ */
3351 static QScriptValue info(QScriptContext* context, QScriptEngine* engine);
52+
53+ /**jsdoc
54+ * Logs a message to the program log and triggers {@link Script.printedMessage}.
55+ * The message logged is the message values separated by spaces.
56+ * <p>If a {@link console.group} is in effect, the message is indented by an amount proportional to the group level.</p>
57+ * @function console.log
58+ * @param {...*} [message] - The message values to log.
59+ * @example <caption>Log some values.</caption>
60+ * Script.printedMessage.connect(function (message, scriptName) {
61+ * console.info("Console.log message:", "\"" + message + "\"", "in", "[" + scriptName + "]");
62+ * });
63+ *
64+ * console.log("string", 7, true);
65+ *
66+ * // string 7 true
67+ * // INFO - Console.log message: "string 7 true" in [console.js]
68+ */
3469 static QScriptValue log(QScriptContext* context, QScriptEngine* engine);
70+
71+ /**jsdoc
72+ * Logs a message to the program log and triggers {@link Script.printedMessage}.
73+ * The message logged is the message values separated by spaces.
74+ * @function console.debug
75+ * @param {...*} [message] - The message values to log.
76+ */
3577 static QScriptValue debug(QScriptContext* context, QScriptEngine* engine);
78+
79+ /**jsdoc
80+ * Logs a "WARNING" message to the program log and triggers {@link Script.warningMessage}.
81+ * The message logged is "WARNING - " followed by the message values separated by spaces.
82+ * @function console.warn
83+ * @param {...*} [message] - The message values to log.
84+ */
3685 static QScriptValue warn(QScriptContext* context, QScriptEngine* engine);
86+
87+ /**jsdoc
88+ * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
89+ * The message logged is "ERROR - " followed by the message values separated by spaces.
90+ * @function console.error
91+ * @param {...*} [message] - The message values to log.
92+ */
3793 static QScriptValue error(QScriptContext* context, QScriptEngine* engine);
94+
95+ /**jsdoc
96+ * A synonym of {@link console.error}.
97+ * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}.
98+ * The message logged is "ERROR - " followed by the message values separated by spaces.
99+ * @function console.exception
100+ * @param {...*} [message] - The message values to log.
101+ */
38102 static QScriptValue exception(QScriptContext* context, QScriptEngine* engine);
103+
104+ /**jsdoc
105+ * Logs an "ERROR" message to the program log and triggers {@link Script.errorMessage}, if a test condition fails.
106+ * The message logged is "ERROR - Assertion failed : " followed by the message values separated by spaces.
107+ * <p>Note: Script execution continues whether or not the test condition fails.</p>
108+ * @function console.assert
109+ * @param {boolean} assertion - The test condition value.
110+ * @param {...*} [message] - The message values to log if the assertion evaluates to <code>false</code>.
111+ * @example <caption>Demonstrate assertion behavior.</caption>
112+ * Script.errorMessage.connect(function (message, scriptName) {
113+ * console.info("Error message logged:", "\"" + message + "\"", "in", "[" + scriptName + "]");
114+ * });
115+ *
116+ * console.assert(5 === 5, "5 equals 5.", "This assertion will succeed."); // No log output.
117+ * console.assert(5 > 6, "5 is not greater than 6.", "This assertion will fail."); // Log output is generated.
118+ * console.info("Script continues running.");
119+ *
120+ * // ERROR - Assertion failed : 5 is not greater than 6. This assertion will fail.
121+ * // INFO - Error message logged: "Assertion failed : 5 is not greater than 6. This assertion will fail." in [console.js]
122+ * // INFO - Script continues running.
123+ */
124+ // Note: Is registered in the script engine as "assert"
39125 static QScriptValue assertion(QScriptContext* context, QScriptEngine* engine);
126+
127+ /**jsdoc
128+ * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent
129+ * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested.
130+ * @function console.group
131+ * @param {*} message - The message value to log.
132+ * @example <caption>Nested groups.</caption>
133+ * console.group("Group 1");
134+ * console.log("Sentence 1");
135+ * console.log("Sentence 2");
136+ * console.group("Group 2");
137+ * console.log("Sentence 3");
138+ * console.log("Sentence 4");
139+ * console.groupEnd();
140+ * console.log("Sentence 5");
141+ * console.groupEnd();
142+ * console.log("Sentence 6");
143+ *
144+ * //Group 1
145+ * // Sentence 1
146+ * // Sentence 2
147+ * // Group 2
148+ * // Sentence 3
149+ * // Sentence 4
150+ * // Sentence 5
151+ * //Sentence 6
152+ */
40153 static QScriptValue group(QScriptContext* context, QScriptEngine* engine);
154+
155+ /**jsdoc
156+ * Has the same behavior as {@link console.group}.
157+ * Logs a message to the program log and triggers {@link Script.printedMessage}, then starts indenting subsequent
158+ * {@link console.log} messages until a {@link console.groupEnd}. Groups may be nested.
159+ * @function console.groupCollapsed
160+ * @param {*} message - The message value to log.
161+ */
41162 static QScriptValue groupCollapsed(QScriptContext* context, QScriptEngine* engine);
163+
164+ /**jsdoc
165+ * Finishes a group of indented {@link console.log} messages.
166+ * @function console.groupEnd
167+ */
42168 static QScriptValue groupEnd(QScriptContext* context, QScriptEngine* engine);
43169
44170 public slots:
171+
172+ /**jsdoc
173+ * Starts a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has
174+ * the timer name and "Timer started".
175+ * @function console.time
176+ * @param {string} name - The name of the timer.
177+ * @example <caption>Time some processing.</caption>
178+ * function sleep(milliseconds) {
179+ * var start = new Date().getTime();
180+ * for (var i = 0; i < 1e7; i++) {
181+ * if ((new Date().getTime() - start) > milliseconds) {
182+ * break;
183+ * }
184+ * }
185+ * }
186+ *
187+ * console.time("MyTimer");
188+ * sleep(1000); // Do some processing.
189+ * console.timeEnd("MyTimer");
190+ *
191+ * // MyTimer: Timer started
192+ * // MyTimer: 1001ms */
45193 void time(QString labelName);
194+
195+ /**jsdoc
196+ * Finishes a timer, logs a message to the program log, and triggers {@link Script.printedMessage}. The message logged has
197+ * the timer name and the number of milliseconds since the timer was started.
198+ * @function console.timeEnd
199+ * @param {string} name - The name of the timer.
200+ */
46201 void timeEnd(QString labelName);
202+
203+ /**jsdoc
204+ * Logs the JavaScript call stack at the point of call to the program log.
205+ * @function console.trace
206+ */
47207 void trace();
208+
209+ /**jsdoc
210+ * Clears the Developer &gt; Scripting &gt; Script Log debug window.
211+ * @function console.clear
212+ */
48213 void clear();
49214
50215 private: