From bbf4ffa65b774f7e28639ca97f2aa02022e75c95 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Tue, 14 Nov 2017 00:08:58 +0100 Subject: [PATCH 01/12] doc: add description for inspector-only console methods. Description inspired by dev tools reference and inspector err messages Added: * intro * console.debug() * console.dirxml() * console.markTimeline() * console.profile() * console.profileEnd() * console.table() * console.timeStamp() * console.timeline() * console.timelineEnd() Fixes: https://github.com/nodejs/node/issues/16755 --- doc/api/console.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/doc/api/console.md b/doc/api/console.md index 54d86cea161feb..1ac99cab839194 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -426,10 +426,101 @@ added: v0.1.100 The `console.warn()` function is an alias for [`console.error()`][]. +## Inspector only methods +The following methods are exposed by the V8 engine in the general API but are non-op unless used +in conjunction with the inspector (`--inspect` flag). + +### console.debug(data[, ...args]) + +* `data` {any} +* `...args` {any} + +The `console.debug()` function is an alias for [`console.log()`][]. + +### console.dirxml(object) + +* `object` {string} + +The `console.dirxml()` method displays in `stdout` an XML interactive tree representation of the descendants +of the specified `object` if possible, or the JavaScript representation if not. Calling +`console.dirxml()` on an HTML or XML element is equivalent to calling `console.log()`. + +### console.markTimeline() + +* `label` {string} Defaults to `'default'`. + +The `console.markTimeline()` method is the deprecated form of [`console.timeStamp()`][]. + +### console.profile([label]) + +* `label` {string} + +The `console.profile()` method starts a JavaScript CPU profile with an optional label until +[`console.profileEnd()`][] is called. The profile is then added to the **Profile** panel of the +inspector. +```js +console.profile('MyLabel'); +// Some code +console.profileEnd(); +// Adds the profile 'MyLabel' to the Profiles panel of the inspector tab. +``` + +### console.profileEnd() + + +Stops the current JavaScript CPU profiling session if one has been started and prints the +report to the **Profiles** panel of the inspector tab. See [`console.profile()`][] for an +example. + +### console.table(array[, ...args]) + +* `array` {array|object} +* `...args` {any} + +Prints to `stdout` the array `array` formatted as a table. + +### console.timeStamp([label]) + +* `label` {string} + +The `console.timeStamp()` method adds an event with the label `label` to the **Timeline** +panel of the inspector tab. + +### console.timeline([label]) + +* `label` {string} Defaults to `'default'`. + +The `console.timeline()` method is the deprecated form of [`console.time()`][]. + +### console.timelineEnd([label]) + +* `label` {string} Defaults to `'default'`. + +The `console.timelineEnd()` method is the deprecated form of [`console.timeEnd()`][]. + [`console.error()`]: #console_console_error_data_args [`console.group()`]: #console_console_group_label [`console.log()`]: #console_console_log_data_args [`console.time()`]: #console_console_time_label +[`console.timeStamp()`]: #console_console_timestamp_label [`console.timeEnd()`]: #console_console_timeend_label [`process.stderr`]: process.html#process_process_stderr [`process.stdout`]: process.html#process_process_stdout From eab906a0d665d9d2356e923c23fd0c99240256e7 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Tue, 14 Nov 2017 13:46:50 +0100 Subject: [PATCH 02/12] doc: add warning for inspector-only methods in console.md Following comments on original PR, added warning in each method's description Fixes: https://github.com/nodejs/node/issues/16755 Refs: https://github.com/nodejs/node/pull/17004#issuecomment-344105512 --- doc/api/console.md | 44 +++++++++++++++++++++++++++----------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index 1ac99cab839194..d3afe61973f637 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -427,8 +427,9 @@ added: v0.1.100 The `console.warn()` function is an alias for [`console.error()`][]. ## Inspector only methods -The following methods are exposed by the V8 engine in the general API but are non-op unless used -in conjunction with the inspector (`--inspect` flag). +The following methods are exposed by the V8 engine in the general API but do +not display anything unless used in conjunction with the inspector tab +(`--inspect` flag). ### console.debug(data[, ...args]) * `object` {string} -The `console.dirxml()` method displays in `stdout` an XML interactive tree representation of the descendants -of the specified `object` if possible, or the JavaScript representation if not. Calling -`console.dirxml()` on an HTML or XML element is equivalent to calling `console.log()`. +This method does not display anything unless used in the inspector. The +`console.dirxml()` method displays in `stdout` an XML interactive tree +representation of the descendants of the specified `object` if possible, or the +JavaScript representation if not. Calling `console.dirxml()` on an HTML or XML +element is equivalent to calling `console.log()`. ### console.markTimeline() * `label` {string} Defaults to `'default'`. -The `console.markTimeline()` method is the deprecated form of [`console.timeStamp()`][]. +This method does not display anything unless used in the inspector. The +`console.markTimeline()` method is the deprecated form of [`console.timeStamp()`][]. ### console.profile([label]) * `label` {string} -The `console.profile()` method starts a JavaScript CPU profile with an optional label until -[`console.profileEnd()`][] is called. The profile is then added to the **Profile** panel of the -inspector. +This method does not display anything unless used in the inspector. The +`console.profile()` method starts a JavaScript CPU profile with an optional +label until [`console.profileEnd()`][] is called. The profile is then added to +the **Profile** panel of the inspector. ```js console.profile('MyLabel'); // Some code @@ -478,9 +483,10 @@ console.profileEnd(); added: v8.0.0 --> -Stops the current JavaScript CPU profiling session if one has been started and prints the -report to the **Profiles** panel of the inspector tab. See [`console.profile()`][] for an -example. +This method does not display anything unless used in the inspector. Stops the +current JavaScript CPU profiling session if one has been started and prints +the report to the **Profiles** panel of the inspector tab. See +[`console.profile()`][] for an example. ### console.table(array[, ...args]) * `label` {string} -The `console.timeStamp()` method adds an event with the label `label` to the **Timeline** -panel of the inspector tab. +This method does not display anything unless used in the inspector. The +`console.timeStamp()` method adds an event with the label `label` to the +**Timeline** panel of the inspector tab. ### console.timeline([label]) * `label` {string} Defaults to `'default'`. -The `console.timeline()` method is the deprecated form of [`console.time()`][]. +This method does not display anything unless used in the inspector. The +`console.timeline()` method is the deprecated form of [`console.time()`][]. ### console.timelineEnd([label]) * `label` {string} Defaults to `'default'`. -The `console.timelineEnd()` method is the deprecated form of [`console.timeEnd()`][]. +This method does not display anything unless used in the inspector. The +`console.timelineEnd()` method is the deprecated form of [`console.timeEnd()`][]. [`console.error()`]: #console_console_error_data_args [`console.group()`]: #console_console_group_label From c95317db73b6afd8dddb6300b48fcd276347162d Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Tue, 14 Nov 2017 15:20:40 +0100 Subject: [PATCH 03/12] doc: add missing references and correcting style Following review, changed one ref and added missing ones. Also corrected casing on non-primitive values. Fixes: https://github.com/nodejs/node/issues/16755 --- doc/api/console.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index d3afe61973f637..6aa705ad33098b 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -492,7 +492,7 @@ the report to the **Profiles** panel of the inspector tab. See -* `array` {array|object} +* `array` {Array|Object} * `...args` {any} This method does not display anything unless used in the inspector. Prints to @@ -529,9 +529,11 @@ This method does not display anything unless used in the inspector. The [`console.error()`]: #console_console_error_data_args [`console.group()`]: #console_console_group_label [`console.log()`]: #console_console_log_data_args +[`console.profile()`]: #console_console_profile_label +[`console.profileEnd()`]: #console_console_profileend [`console.time()`]: #console_console_time_label -[`console.timeStamp()`]: #console_console_timestamp_label [`console.timeEnd()`]: #console_console_timeend_label +[`console.timeStamp()`]: #console_console_timestamp_label [`process.stderr`]: process.html#process_process_stderr [`process.stdout`]: process.html#process_process_stdout [`util.format()`]: util.html#util_util_format_format_args From 757f182bc05936fa806de7c36d57377918f16085 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Tue, 14 Nov 2017 20:18:32 +0100 Subject: [PATCH 04/12] doc: add link to debugger.html in inspector methods intro Following review on PR Fixes: https://github.com/nodejs/node/issues/16755 --- doc/api/console.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/console.md b/doc/api/console.md index 6aa705ad33098b..7a62c6407deb22 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -428,7 +428,7 @@ The `console.warn()` function is an alias for [`console.error()`][]. ## Inspector only methods The following methods are exposed by the V8 engine in the general API but do -not display anything unless used in conjunction with the inspector tab +not display anything unless used in conjunction with the [inspector][] tab (`--inspect` flag). ### console.debug(data[, ...args]) @@ -539,5 +539,6 @@ This method does not display anything unless used in the inspector. The [`util.format()`]: util.html#util_util_format_format_args [`util.inspect()`]: util.html#util_util_inspect_object_options [customizing `util.inspect()` colors]: util.html#util_customizing_util_inspect_colors +[inspector]: debugger.html [note on process I/O]: process.html#process_a_note_on_process_i_o [web-api-assert]: https://developer.mozilla.org/en-US/docs/Web/API/console/assert From 1bef3075eece14b64d8569208de4c65e8cbf092d Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Tue, 14 Nov 2017 22:34:53 +0100 Subject: [PATCH 05/12] doc: corrected nits to console.md Following review, removed tab references. Fixes: https://github.com/nodejs/node/issues/16755 --- doc/api/console.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index 7a62c6407deb22..458ed8ee98fed7 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -428,7 +428,7 @@ The `console.warn()` function is an alias for [`console.error()`][]. ## Inspector only methods The following methods are exposed by the V8 engine in the general API but do -not display anything unless used in conjunction with the [inspector][] tab +not display anything unless used in conjunction with the [inspector][] (`--inspect` flag). ### console.debug(data[, ...args]) @@ -475,7 +475,7 @@ the **Profile** panel of the inspector. console.profile('MyLabel'); // Some code console.profileEnd(); -// Adds the profile 'MyLabel' to the Profiles panel of the inspector tab. +// Adds the profile 'MyLabel' to the Profiles panel of the inspector. ``` ### console.profileEnd() @@ -485,7 +485,7 @@ added: v8.0.0 This method does not display anything unless used in the inspector. Stops the current JavaScript CPU profiling session if one has been started and prints -the report to the **Profiles** panel of the inspector tab. See +the report to the **Profiles** panel of the inspector. See [`console.profile()`][] for an example. ### console.table(array[, ...args]) @@ -506,7 +506,7 @@ added: v8.0.0 This method does not display anything unless used in the inspector. The `console.timeStamp()` method adds an event with the label `label` to the -**Timeline** panel of the inspector tab. +**Timeline** panel of the inspector. ### console.timeline([label]) -* `data` {any} -* `...args` {any} - -The `console.debug()` function is an alias for [`console.log()`][]. - ### console.dirxml(object) * `data` {any} * `...args` {any} From 343a92db24f5e7e1568145c9a122467f1b688a57 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Sat, 18 Nov 2017 15:19:52 +0100 Subject: [PATCH 08/12] doc: replace pseudo version number with constant Following review, replaced pseudo version number with REPLACEME Refs: https://github.com/nodejs/node/pull/17004#pullrequestreview-77616899 Fixes: https://github.com/nodejs/node/issues/16755 --- doc/api/console.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/console.md b/doc/api/console.md index c102508be5a4ee..e27144ca9a1368 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -240,7 +240,7 @@ undefined ### console.debug(data[, ...args]) * `data` {any} * `...args` {any} From 0d065950a3b8aad453b81ba335c51cfdbda8aaba Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Sat, 18 Nov 2017 21:18:19 +0100 Subject: [PATCH 09/12] doc: add changes version number and missing arguments Following reviews --- doc/api/console.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index e27144ca9a1368..8faf5ab8f4a5ef 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -240,7 +240,8 @@ undefined ### console.debug(data[, ...args]) * `data` {any} * `...args` {any} @@ -443,7 +444,7 @@ representation of the descendants of the specified `object` if possible, or the JavaScript representation if not. Calling `console.dirxml()` on an HTML or XML element is equivalent to calling `console.log()`. -### console.markTimeline() +### console.markTimeline(label) From 9ffff7b0f3b9b04eb14905c477660fed9713fae6 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Sun, 19 Nov 2017 16:04:06 +0100 Subject: [PATCH 10/12] doc: fixed versionning block Following review --- doc/api/console.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/console.md b/doc/api/console.md index 8faf5ab8f4a5ef..f422d7701ac9e2 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -241,7 +241,10 @@ undefined ### console.debug(data[, ...args]) * `data` {any} * `...args` {any} From 38f49c2c1490cd70c4a711ba80fed2fc2f03c912 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Sun, 19 Nov 2017 20:43:25 +0100 Subject: [PATCH 11/12] doc: double quoting yaml value starting with backticks Make and make test return yaml linting errors on first parsing. --- doc/api/console.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/console.md b/doc/api/console.md index f422d7701ac9e2..d2414f22d920ca 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -244,7 +244,7 @@ added: v8.0.0 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/17033 - description: `console.debug` is now an alias for `console.log`. + description: "`console.debug` is now an alias for `console.log`." --> * `data` {any} * `...args` {any} From 1d9981f1abf66482d919b59f4877f73c91bcc655 Mon Sep 17 00:00:00 2001 From: Benjamin Zaslavsky Date: Mon, 20 Nov 2017 09:09:29 +0100 Subject: [PATCH 12/12] doc: fix console.table signature Replacing rest operator with column parameter Ref: https://github.com/nodejs/node/pull/17004#pullrequestreview-77661094 --- doc/api/console.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/console.md b/doc/api/console.md index d2414f22d920ca..ba1505ec1d0f21 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -483,12 +483,12 @@ current JavaScript CPU profiling session if one has been started and prints the report to the **Profiles** panel of the inspector. See [`console.profile()`][] for an example. -### console.table(array[, ...args]) +### console.table(array[, columns]) * `array` {Array|Object} -* `...args` {any} +* `columns` {Array} This method does not display anything unless used in the inspector. Prints to `stdout` the array `array` formatted as a table.