Consistent documentation for console printing methods (#34284)

mdn · Jun 21, 2024 · c607327 · c607327
1 parent dc25471
commit c607327
Show file tree

Hide file tree

Showing 8 changed files with 86 additions and 89 deletions.
diff --git a/files/en-us/web/api/console/assert_static/index.md b/files/en-us/web/api/console/assert_static/index.md
@@ -15,9 +15,9 @@ The **`console.assert()`** static method writes an error message to the console
 ```js-nolint
 assert(assertion)
 
-assert(assertion, obj1)
-assert(assertion, obj1, obj2)
-assert(assertion, obj1, obj2, /* …, */ objN)
+assert(assertion, val1)
+assert(assertion, val1, val2)
+assert(assertion, val1, val2, /* …, */ valN)
 
 assert(assertion, msg)
 assert(assertion, msg, subst1)
@@ -28,12 +28,14 @@ assert(assertion, msg, subst1, /* …, */ substN)
 
 - `assertion`
  - : Any boolean expression. If the assertion is false, a generic message indicating assertion failure is written to the console.
-- `obj1` … `objN`
- - : A list of JavaScript objects to output. A representation of each of these objects is output to the console after a generic assertion failure message (which may be different from the message output when these objects are not present) in the order given with some type of separation between the message and between each of them. There is a special case if `obj1` is a string, which is described subsequently.
+- `val1` … `valN`
+ - : A list of JavaScript values to output. A representation of each of these values is output to the console after a generic assertion failure message (which may be different from the message output when these values are not present) in the order given with some type of separation between the message and between each of them. There is a special case if `obj1` is a string, which is described subsequently.
 - `msg`
- - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order up to the number of substitution strings. A colon, a space, and then the substituted string are appended to the generic assertion message to form a detailed assertion message, and the result is output to the console.
+ - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order up to the number of substitution strings. A colon, a space, and then the substituted string are appended to the generic assertion message to form a detailed assertion message, and the result is output to the console. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
 - `subst1` … `substN`
- - : JavaScript objects with which to replace substitution strings within `msg`. This gives you additional control over the format of the output. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work. If there are more substutition objects than there are substitution strings, the extra objects are themselves written to the console after the detailed assertion message in the same manner as described for objects written after a generic assertion message.
+ - : JavaScript values with which to replace substitution strings within `msg`. If there are more substutition values than there are substitution strings, the extra values are themselves written to the console after the detailed assertion message in the same manner as when there's no format string.
+
+See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of {{domxref("console")}} for further details.
 
 ### Return value
 
@@ -58,8 +60,6 @@ for (let number = 2; number <= 5; number++) {
 // Assertion failed: {number: 5, errorMsg: "the # is not even"}
 ```
 
-See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) in the documentation of {{domxref("console")}} for further details.
-
 ## Specifications
 
 {{Specifications}}

diff --git a/files/en-us/web/api/console/debug_static/index.md b/files/en-us/web/api/console/debug_static/index.md
@@ -13,22 +13,22 @@ The **`console.debug()`** static method outputs a message to the console at the
 ## Syntax
 
 ```js-nolint
-debug(obj1)
-debug(obj1, /* …, */ objN)
+debug(val1)
+debug(val1, /* …, */ valN)
 debug(msg)
 debug(msg, subst1, /* …, */ substN)
 ```
 
 ### Parameters
 
-- `obj1` … `objN`
- - : A list of JavaScript objects to output. The string representations of each of these objects are appended together in the order listed and output to the console.
+- `val1` … `valN`
+ - : A list of JavaScript values to output. A representation of each of these values is output to the console in the order given with some type of separation between each of them. There is a special case if `obj1` is a string, which is described subsequently.
 - `msg`
- - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order.
+ - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order up to the number of substitution strings. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
 - `subst1` … `substN`
- - : JavaScript objects with which to replace substitution strings within `msg`. This gives you additional control over the format of the output. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
+ - : JavaScript values with which to replace substitution strings within `msg`. If there are more substutition values than there are substitution strings, the extra values are themselves written to the console after the detailed assertion message in the same manner as when there's no format string.
 
-See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of the {{domxref("console")}} object for details.
+See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of {{domxref("console")}} for further details.
 
 ### Return value
 

diff --git a/files/en-us/web/api/console/dir_static/index.md b/files/en-us/web/api/console/dir_static/index.md
@@ -10,7 +10,7 @@ browser-compat: api.console.dir_static
 
 The **`console.dir()`** static method displays a list of the properties of the specified JavaScript object. In browser consoles, the output is presented as a hierarchical listing with disclosure triangles that let you see the contents of child objects.
 
-In other words, `console.dir()` is the way to see all the properties of a specified JavaScript object in the console.
+Unlike other logging methods, `console.dir()` does not attempt to pretty-print the object. For example, if you pass a DOM element to `console.dir()`, it will not be displayed like in the element inspector, but will instead show a list of properties.
 
 ![A screenshot of the Firefox console where console.dir(document.location) is run. We can see the URL of the page, followed by a block of properties. If the property is a function or an object, a disclosure triangle is prepended.](console-dir.png)
 

diff --git a/files/en-us/web/api/console/error_static/index.md b/files/en-us/web/api/console/error_static/index.md
@@ -8,27 +8,27 @@ browser-compat: api.console.error_static
 
 {{APIRef("Console API")}} {{AvailableInWorkers}}
 
-The **`console.error()`** static method outputs an error message to the console.
+The **`console.error()`** static method outputs a message to the console at the "error" log level. The message is only displayed to the user if the console is configured to display error output. In most cases, the log level is configured within the console UI. The message may be formatted as an error, with red colors and call stack information.
 
 ## Syntax
 
 ```js-nolint
-error(obj1)
-error(obj1, /* …, */ objN)
+error(val1)
+error(val1, /* …, */ valN)
 error(msg)
 error(msg, subst1, /* …, */ substN)
 ```
 
 ### Parameters
 
-- `obj1` … `objN`
- - : A list of JavaScript objects to output. The string representations of each of these objects are appended together in the order listed and output to the console.
+- `val1` … `valN`
+ - : A list of JavaScript values to output. A representation of each of these values is output to the console in the order given with some type of separation between each of them. There is a special case if `obj1` is a string, which is described subsequently.
 - `msg`
- - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order.
+ - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order up to the number of substitution strings. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
 - `subst1` … `substN`
- - : JavaScript objects with which to replace substitution strings within `msg`. This gives you additional control over the format of the output. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
+ - : JavaScript values with which to replace substitution strings within `msg`. If there are more substutition values than there are substitution strings, the extra values are themselves written to the console after the detailed assertion message in the same manner as when there's no format string.
 
-See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of the {{domxref("console")}} object for details.
+See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of {{domxref("console")}} for further details.
 
 ### Return value
 

diff --git a/files/en-us/web/api/console/index.md b/files/en-us/web/api/console/index.md
@@ -30,13 +30,13 @@ This page documents the [Methods](#methods) available on the `console` object an
 - {{domxref("console/countReset_static", "console.countReset()")}}
  - : Resets the value of the counter with the given label.
 - {{domxref("console/debug_static", "console.debug()")}}
- - : Outputs a message to the console with the log level `debug`.
+ - : Outputs a message to the console with the debug log level.
 - {{domxref("console/dir_static", "console.dir()")}}
  - : Displays an interactive listing of the properties of a specified JavaScript object. This listing lets you use disclosure triangles to examine the contents of child objects.
 - {{domxref("console/dirxml_static", "console.dirxml()")}}
  - : Displays an XML/HTML Element representation of the specified object if possible or the JavaScript Object view if it is not possible.
 - {{domxref("console/error_static", "console.error()")}}
- - : Outputs an error message. You may use [string substitution](#using_string_substitutions) and additional arguments with this method.
+ - : Outputs a message to the console with the error log level.
 - `console.exception()` {{Non-standard_inline}} {{deprecated_inline}}
  - : An alias for `console.error()`.
 - {{domxref("console/group_static", "console.group()")}}
@@ -46,9 +46,9 @@ This page documents the [Methods](#methods) available on the `console` object an
 - {{domxref("console/groupEnd_static", "console.groupEnd()")}}
  - : Exits the current inline [group](#using_groups_in_the_console).
 - {{domxref("console/info_static", "console.info()")}}
- - : Informative logging of information. You may use [string substitution](#using_string_substitutions) and additional arguments with this method.
+ - : Outputs a message to the console with the info log level.
 - {{domxref("console/log_static", "console.log()")}}
- - : For general output of logging information. You may use [string substitution](#using_string_substitutions) and additional arguments with this method.
+ - : Outputs a message to the console.
 - {{domxref("console/profile_static", "console.profile()")}} {{Non-standard_inline}}
  - : Starts the browser's built-in profiler (for example, the [Firefox performance tool](https://firefox-source-docs.mozilla.org/devtools-user/performance/index.html)). You can specify an optional name for the profile.
 - {{domxref("console/profileEnd_static", "console.profileEnd()")}} {{Non-standard_inline}}
@@ -66,7 +66,7 @@ This page documents the [Methods](#methods) available on the `console` object an
 - {{domxref("console/trace_static", "console.trace()")}}
  - : Outputs a [stack trace](#stack_traces).
 - {{domxref("console/warn_static", "console.warn()")}}
- - : Outputs a warning message. You may use [string substitution](#using_string_substitutions) and additional arguments with this method.
+ - : Outputs a message to the console with the warning log level.
 
 ## Examples
 
@@ -94,6 +94,28 @@ The output looks something like this:
 {str:"Some text", id:5}
 ```
 
+The browser will display as much information about the object as it can and wishes to. For example, private state of the object may be displayed too. Certain types of objects, such as DOM elements or functions, may also be displayed in a special way.
+
+#### Snapshotting objects
+
+Information about an object is lazily retrieved. This means that the log message shows the content of an object at the time when it's first viewed, not when it was logged. For example:
+
+```js
+const obj = {};
+console.log(obj);
+obj.prop = 123;
+```
+
+This will output `{}`. However, if you expand the object's details, you will see `prop: 123`.
+
+If you are going to mutate your object and you want to prevent the logged information from being updated, you can [deep-clone](/en-US/docs/Glossary/Deep_copy) the object before logging it. A common way is to {{jsxref("JSON.stringify()")}} and then {{jsxref("JSON.parse()")}} it:
+
+```js
+console.log(JSON.parse(JSON.stringify(obj)));
+```
+
+There are other alternatives that work in browsers, such as [`structuredClone()`](/en-US/docs/Web/API/structuredClone), which are more effective at cloning different types of objects.
+
 #### Outputting multiple objects
 
 You can also output multiple objects by listing them when calling the logging method, like this:
@@ -112,18 +134,22 @@ My first car was a Dodge Charger. The object is: {str:"Some text", id:5}
 
 #### Using string substitutions
 
-When passing a string to one of the `console` object's methods that accepts a string (such as `console.log()`), you may use these substitution strings:
+The first parameter to the logging methods can be a string containing zero or more substitution strings. Each substitution string is replaced by the corresponding argument value.
 
-- `%o` or `%O`
- - : Outputs a JavaScript object. Clicking the object name opens more information about it in the inspector.
+- `%o`
+ - : Outputs a JavaScript object in the "optimally useful formatting" style, for example DOM elements may be displayed the same way as they would appear in the element inspector.
+- `%O`
+ - : Outputs a JavaScript object in the "generic JavaScript object formatting" style, usually in the form of an expandable tree. This is similar to {{domxref("console/dir_static", "console.dir()")}}.
 - `%d` or `%i`
- - : Outputs an integer. Number formatting is supported, for example `console.log("Foo %.2d", 1.1)` will output the number as two significant figures with a leading 0: `Foo 01`.
+ - : Outputs an integer.
 - `%s`
  - : Outputs a string.
 - `%f`
- - : Outputs a floating-point value. Formatting is supported, for example `console.log("Foo %.2f", 1.1)` will output the number to 2 decimal places: `Foo 1.10`.
+ - : Outputs a floating-point value.
+- `%c`
+ - : Applies CSS style rules to all following text. See [Styling console output](#styling_console_output).
 
-> **Note:** Precision formatting doesn't work in Chrome.
+Some browsers may implement additional format specifiers. For example, Safari and Firefox support the C-style precision formating `%.<precision>f`. For example `console.log("Foo %.2f", 1.1)` will output the number to 2 decimal places: `Foo 1.10`, while `console.log("Foo %.2d", 1.1)` will output the number as two significant figures with a leading 0: `Foo 01`.
 
 Each of these pulls the next argument after the format string off the parameter list. For example:
 
@@ -262,18 +288,11 @@ The output in the console looks something like this:
 
 {{Compat}}
 
-## Notes
-
-- At least in Firefox, if a page defines a `console` object, that object overrides the one built into Firefox.
-
 ## See also
 
 - [Firefox Developer Tools](https://firefox-source-docs.mozilla.org/devtools-user/index.html)
 - [Web console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html) — how the Web console in Firefox handles console API calls
 - [about:debugging](https://firefox-source-docs.mozilla.org/devtools-user/about_colon_debugging/index.html) — how to see console output when the debugging target is a mobile device
-
-### Other implementations
-
 - [Google Chrome DevTools](https://developer.chrome.com/docs/devtools/console/api/)
 - [Microsoft Edge DevTools](https://docs.microsoft.com/archive/microsoft-edge/legacy/developer/)
 - [Safari Web Inspector](https://developer.apple.com/library/archive/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Console/Console.html)
diff --git a/files/en-us/web/api/console/info_static/index.md b/files/en-us/web/api/console/info_static/index.md
@@ -8,27 +8,27 @@ browser-compat: api.console.info_static
 
 {{APIRef("Console API")}} {{AvailableInWorkers}}
 
-The **`console.info()`** static method outputs an informational message to the console. In Firefox, a small "i" icon is displayed next to these items in the console's log.
+The **`console.info()`** static method outputs a message to the console at the "info" log level. The message is only displayed to the user if the console is configured to display info output. In most cases, the log level is configured within the console UI. The message may receive special formatting, such as a small "i" icon next to it.
 
 ## Syntax
 
 ```js-nolint
-info(obj1)
-info(obj1, /* …, */ objN)
+info(val1)
+info(val1, /* …, */ valN)
 info(msg)
 info(msg, subst1, /* …, */ substN)
 ```
 
 ### Parameters
 
-- `obj1` … `objN`
- - : A list of JavaScript objects to output. The string representations of each of these objects are appended together in the order listed and output to the console.
+- `val1` … `valN`
+ - : A list of JavaScript values to output. A representation of each of these values is output to the console in the order given with some type of separation between each of them. There is a special case if `obj1` is a string, which is described subsequently.
 - `msg`
- - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order.
+ - : A JavaScript string containing zero or more substitution strings, which are replaced with `subst1` through `substN` in consecutive order up to the number of substitution strings. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
 - `subst1` … `substN`
- - : JavaScript objects with which to replace substitution strings within `msg`. This gives you additional control over the format of the output. See [Using string substitutions](/en-US/docs/Web/API/console#using_string_substitutions) for a description of how substitutions work.
+ - : JavaScript values with which to replace substitution strings within `msg`. If there are more substutition values than there are substitution strings, the extra values are themselves written to the console after the detailed assertion message in the same manner as when there's no format string.
 
-See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of the {{domxref("console")}} object for details.
+See [Outputting text to the console](/en-US/docs/Web/API/console#outputting_text_to_the_console) in the documentation of {{domxref("console")}} for further details.
 
 ### Return value