Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make warnings consistent in the JS docs #4609

Merged
merged 1 commit into from
Apr 30, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -495,7 +495,7 @@ <h3 id="Object_literals">Object literals</h3>
<p>An object literal is a list of zero or more pairs of property names and associated values of an object, enclosed in curly braces (<code>{}</code>).</p>

<div class="notecard warning">
<p><strong>Note:</strong> Do not use an object literal at the beginning of a statement! This will lead to an error (or not behave as you expect), because the <code>{</code> will be interpreted as the beginning of a block.</p>
<p><strong>Warning:</strong> Do not use an object literal at the beginning of a statement! This will lead to an error (or not behave as you expect), because the <code>{</code> will be interpreted as the beginning of a block.</p>
</div>

<p>The following is an example of an object literal. The first element of the <code>car</code> object defines a property, <code>myCar</code>, and assigns to it a new string, "<code>Saturn</code>"; the second element, the <code>getCar</code> property, is immediately assigned the result of invoking the function <code>(carTypes("Honda"))</code>; the third element, the <code>special</code> property, uses an existing variable (<code>sales</code>).</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -378,7 +378,7 @@ <h3 id="Summary_of_methods_for_extending_the_prototype_chain">Summary of methods

<h4 class="name">#1: New initialization</h4>
<div class="notecard warning">
<p>One misfeature that is often used is to extend <code>Object.prototype</code> or one of the other built-in prototypes.</p>
<p><strong>Warning:</strong> One misfeature that is often used is to extend <code>Object.prototype</code> or one of the other built-in prototypes.</p>

<p>This technique is called monkey patching and breaks <em>encapsulation</em>. While used by popular frameworks such as Prototype.js, there is still no good reason for cluttering built-in types with additional <em>non-standard</em> functionality.</p>

Expand Down
2 changes: 1 addition & 1 deletion files/en-us/web/javascript/reference/classes/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ <h3 id="Instance_properties">Instance properties</h3>
<h3 id="Field_declarations">Field declarations</h3>

<div class="warning">
<p>Public and private field declarations are an <a href="https://github.com/tc39/proposal-class-fields">experimental feature (stage 3)</a> proposed at <a href="https://tc39.es">TC39</a>, the JavaScript standards committee. Support in browsers is limited, but the feature can be used through a build step with systems like <a href="https://babeljs.io/">Babel</a>.</p>
<p><strong>Warning:</strong> Public and private field declarations are an <a href="https://github.com/tc39/proposal-class-fields">experimental feature (stage 3)</a> proposed at <a href="https://tc39.es">TC39</a>, the JavaScript standards committee. Support in browsers is limited, but the feature can be used through a build step with systems like <a href="https://babeljs.io/">Babel</a>.</p>
</div>

<h4 id="Public_field_declarations">Public field declarations</h4>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
---
<div>{{jsSidebar("More")}}</div>

<div class="warning"><strong>Non-standard.</strong> The legacy iterator protocol was a SpiderMonkey-specific feature, which is removed in Firefox 58+. For future-facing usages, consider using <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of">for..of</a> loops and the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols">iterator protocol</a>.</div>
<div class="warning"><p><strong>Warning:</strong> The legacy iterator protocol was a SpiderMonkey-specific feature, which is removed in Firefox 58+. For future-facing usages, consider using <a href="/en-US/docs/Web/JavaScript/Reference/Statements/for...of">for..of</a> loops and the <a href="/en-US/docs/Web/JavaScript/Reference/Iteration_protocols">iterator protocol</a>.</p></div>

<h2 id="The_deprecated_Firefox-only_iterator_protocol">The deprecated Firefox-only iterator protocol</h2>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ <h2 id="Description">Description</h2>

<p><code>callee</code> is a property of the <code>arguments</code> object. It can be used to refer to the currently executing function inside the function body of that function. This is useful when the name of the function is unknown, such as within a function expression with no name (also called "anonymous functions").</p>

<div class="warning"><strong>Warning:</strong> The 5th edition of ECMAScript (ES5) forbids use of <code>arguments.callee()</code> in <a href="/en-US/docs/JavaScript/Reference/Functions_and_function_scope/Strict_mode">strict mode</a>. Avoid using <code>arguments.callee()</code> by either giving function expressions a name or use a function declaration where a function must call itself.</div>
<div class="warning"><p><strong>Warning:</strong> The 5th edition of ECMAScript (ES5) forbids use of <code>arguments.callee()</code> in <a href="/en-US/docs/JavaScript/Reference/Functions_and_function_scope/Strict_mode">strict mode</a>. Avoid using <code>arguments.callee()</code> by either giving function expressions a name or use a function declaration where a function must call itself.</p></div>

<h3 id="Why_was_arguments.callee_removed_from_ES5_strict_mode">Why was <code>arguments.callee</code> removed from ES5 strict mode?</h3>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ <h2 id="Description">Description</h2>
<p>The string conversions of all array elements are joined into one string.</p>

<div class="warning">
<p>If an element is <code>undefined</code>, <code>null</code> or an empty array
<p><strong>Warning:</strong> If an element is <code>undefined</code>, <code>null</code> or an empty array
<code>[]</code>, it is converted to an empty string.</p>
</div>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ <h3 id="Iteration_using_.next">Iteration using .next()</h3>
iteraror.next().value; // undefined </pre>

<div class="notecard warning">
<p>One-use: the array iterator object is one use or temporary object</p>
<p><strong>Warning:</strong> The array iterator object is one use or temporary object</p>
</div>

<p>example:</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ <h3 id="Custom_Error_Types">Custom Error Types</h3>
<h4 id="ES6_Custom_Error_Class">ES6 Custom Error Class</h4>

<div class="notecard warning">
<p>Versions of Babel prior to 7 can handle <code>CustomError</code> class methods, but only when they are declared with <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty">Object.defineProperty()</a>. Otherwise, old versions of Babel and other transpilers will not correctly handle the following code without <a href="https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend">additional configuration</a>.</p>
<p><strong>Warning:</strong> Versions of Babel prior to 7 can handle <code>CustomError</code> class methods, but only when they are declared with <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty">Object.defineProperty()</a>. Otherwise, old versions of Babel and other transpilers will not correctly handle the following code without <a href="https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend">additional configuration</a>.</p>
</div>

<div class="notecard note">
Expand Down Expand Up @@ -155,7 +155,7 @@ <h4 id="ES6_Custom_Error_Class">ES6 Custom Error Class</h4>
<h4 id="ES5_Custom_Error_Object">ES5 Custom Error Object</h4>

<div class="warning">
<p><strong>All</strong> browsers include the <code>CustomError</code> constructor in the stack trace when using a prototypal declaration.</p>
<p><strong>Warning:</strong> All browsers include the <code>CustomError</code> constructor in the stack trace when using a prototypal declaration.</p>
</div>

<pre class="brush: js">function CustomError(foo, message, fileName, lineNumber) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
---
<div>{{jsSidebar("Objects")}}</div>

<div class="warning"><strong>Warning:</strong> Although <code>escape()</code> is not
<div class="warning"><p><strong>Warning:</strong> Although <code>escape()</code> is not
strictly deprecated (as in "removed from the Web standards"), it is defined in <a
href="https://www.ecma-international.org/ecma-262/9.0/index.html#sec-additional-ecmascript-features-for-web-browsers">Annex
B</a> of the ECMA-262 standard, whose introduction states:
B</a> of the ECMA-262 standard, whose introduction states:</p>

<blockquote>… All of the language features and behaviors specified in this annex have
one or more undesirable characteristics and in the absence of legacy usage would be
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,9 @@ <h3 id="Unicode_calendar_keys">Unicode calendar keys</h3>
</tr>
<tr>
<td>
<div class="notecard warning">The <code>islamicc</code> calendar key has been deprecated. Please use <code>islamic-civil</code>.</div>
<div class="notecard warning">
<p><strong>Warning:</strong> The <code>islamicc</code> calendar key has been deprecated. Please use <code>islamic-civil</code>.</p>
</div>

<p><code>islamicc</code></p>
</td>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ <h3 id="Valid_collation_types">Valid collation types</h3>
<tr>
<td>
<div class="notecard warning">
<p>The <code>direct</code> collation type has been deprected. Do not use.</p>
<p><strong>Warning:</strong> The <code>direct</code> collation type has been deprected. Do not use.</p>
</div>
<p>direct</p>
</td>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<div>{{JSRef}}</div>

<div class="warning">
<p>This feature is deprecated in favor of defining getters using the <a
<p><strong>Warning:</strong> This feature is deprecated in favor of defining getters using the <a
href="/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer">object
initializer syntax</a> or the {{jsxref("Object.defineProperty()")}} API. While this
feature is widely implemented, it is only described in the <a
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<div>{{JSRef}}</div>

<div class="warning">
<p>This feature is deprecated in favor of defining setters using the <a
<p><strong>Warning:</strong> This feature is deprecated in favor of defining setters using the <a
href="/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer">object
initializer syntax</a> or the {{jsxref("Object.defineProperty()")}} API.</p>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,12 @@ <h3 id="Parameters">Parameters</h3>
<code><var>string</var></code>. Be careful—this does <strong><em>not</em></strong>
default to <code>10</code>! If the radix value is not of the <code>Number</code> type
it will be coerced to a <code>Number</code></dd>
<dd class="notecard warning">The <a href="#description">description below</a> explains
in more detail what happens when <code><var>radix</var></code> is not provided.</dd>
<dd><div class="notecard warning">
<p><strong>Warning:</strong> The <a href="#description">description below</a> explains
in more detail what happens when <code><var>radix</var></code> is not provided.
</p>
</div>
</dd>
</dl>

<h3 id="Return_value">Return value</h3>
Expand Down Expand Up @@ -113,7 +117,7 @@ <h2 id="Description">Description</h2>
<code><var>thatNumber</var>.toString(<var>radix</var>)</code>.</p>

<div class="notecard warning">
<p><strong>{{jsxref("BigInt")}} Warning:</strong> <code>parseInt</code> converts a
<p><strong>Warning:</strong> <code>parseInt</code> converts a
{{jsxref("BigInt")}} to a {{jsxref("Number")}} and loses precision in the process.
This is because trailing non-numeric values, including "<code>n</code>", are
discarded.</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ <h3 id="Return_value">Return value</h3>
{{jsxref("Promise")}}.</p>

<div class="warning">
<p>Note the examples below are throwing instances of <a
<p><strong>Warning:</strong> The examples below are throwing instances of <a
href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a>. This is
considered good practice in contrast to throwing Strings; otherwise, the part doing
the catching would have to perform checks to see if the argument was a string or an
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
<code>&lt;/a&gt;</code> end tag.</p>

<div class="notecard warning">
<p>Don't use this method. Use <a href="/en-US/docs/Web/API/Document_Object_Model">DOM
<p><strong>Warning:</strong> Don't use this method. Use <a href="/en-US/docs/Web/API/Document_Object_Model">DOM
APIs</a> instead. Also, the HTML specification no longer allows the
{{HTMLElement("a")}} element to have a <code>name</code> attribute, so this method
doesn't even create valid markup.</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,7 @@ <h2 id="Description">Description</h2>
</ul>

<div class="notecard warning">
<p><strong>Do NOT rely on exact return values of <code>-1</code> or <code>1</code>!
</strong></p>
<p><strong>Warning:</strong> Do not rely on exact return values of <code>-1</code> or <code>1</code>!</p>

<p>Negative and positive integer results vary between browsers (as well as between
browser versions) because the W3C specification only mandates negative and positive
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ <h3 id="Splitting_with_a_RegExp_to_include_parts_of_the_separator_in_the_result"
<h3 id="Reversing_a_String_using_split">Reversing a String using <code>split()</code></h3>

<div class="warning">
<p>This is not a robust way to reverse a string:</p>
<p><strong>Warning:</strong> This is not a robust way to reverse a string:</p>

<pre class="brush: js example-bad">const str = 'asdfghjkl'
const strReverse = str.split('').reverse().join('')
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ <h3 id="Iteration_using_.next">Iteration using .next()</h3>
iteraror.next().value; // undefined </pre>

<div class="notecard warning">
<p>One-use: the array iterator object is one use or temporary object</p>
<p><strong>Warning:</strong> One-use: the array iterator object is one use or temporary object</p>
</div>

<p>example:</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@
---
<p>{{jsSidebar("Objects")}}</p>

<div class="warning">Warning: Although <code>unescape()</code> is not strictly deprecated
<div class="warning"><p><strong>Warning:</strong> Although <code>unescape()</code> is not strictly deprecated
(as in "removed from the Web standards"), it is defined in <a
href="https://www.ecma-international.org/ecma-262/9.0/index.html#sec-additional-ecmascript-features-for-web-browsers">Annex
B</a> of the ECMA-262 standard, whose introduction states:
B</a> of the ECMA-262 standard, whose introduction states:</p>
<blockquote>… All of the language features and behaviors specified in this annex have
one or more undesirable characteristics and in the absence of legacy usage would be
removed from this specification. …<br>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<h2 id="Syntax">Syntax</h2>

<div class="warning">
<p><strong>Important</strong>: Since instantiation for large modules can be expensive,
<p><strong>Warning:</strong> Since instantiation for large modules can be expensive,
developers should only use the <code>Instance()</code> constructor when synchronous
instantiation is absolutely required; the asynchronous
{{jsxref("WebAssembly.instantiateStreaming()")}} method should be used at all other
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
</ul>

<div class="warning">
<p><strong>Important</strong>: This method is not the most efficient way of fetching and
<p><strong>Warning:</strong> This method is not the most efficient way of fetching and
instantiating wasm modules. If at all possible, you should use the newer
{{jsxref("WebAssembly.instantiateStreaming()")}} method instead, which fetches,
compiles, and instantiates a module all in one step, directly from the raw bytecode,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
<h2 id="Syntax">Syntax</h2>

<div class="warning">
<p><strong>Important</strong>: Since compilation for large modules can be expensive,
<p><strong>Warning:</strong> Since compilation for large modules can be expensive,
developers should only use the <code>Module()</code> constructor when synchronous
compilation is absolutely required; the asynchronous
{{jsxref("WebAssembly.compileStreaming()")}} method should be used at all other times.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ <h2 id="Hashbang_comments">Hashbang comments</h2>
</div>

<div class="notecard warning">
<p>Although <a href="https://en.wikipedia.org/wiki/Byte_order_mark">BOM</a> before hashbang comment will work in a browser it is not advised to use BOM in a script with hasbang. BOM will not work when you try to run the script in Unix/Linux. So use UTF-8 without BOM if you want to run scripts directly from shell.</p>
<p><strong>Warning:</strong> Although <a href="https://en.wikipedia.org/wiki/Byte_order_mark">BOM</a> before hashbang comment will work in a browser it is not advised to use BOM in a script with hasbang. BOM will not work when you try to run the script in Unix/Linux. So use UTF-8 without BOM if you want to run scripts directly from shell.</p>
</div>

<p>You must only use the <code>#!</code> comment style to specify a JavaScript interpreter. In all other cases just use a <code>//</code> comment (or mulitiline comment).</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ <h3 id="Spread_properties">Spread properties</h3>
// Object { foo: "baz", x: 42, y: 13 }</pre>

<div class="notecard warning">
<p>Note that {{jsxref("Object.assign()")}} triggers <a href="/en-US/docs/Web/JavaScript/Reference/Functions/set">setters</a>, whereas the spread operator doesn't!</p>
<p><strong>Warning:</strong> Note that {{jsxref("Object.assign()")}} triggers <a href="/en-US/docs/Web/JavaScript/Reference/Functions/set">setters</a>, whereas the spread operator doesn't!</p>
</div>

<h3 id="Prototype_mutation">Prototype mutation</h3>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ <h2 id="Description">Description</h2>
generators offer enormous power and control.</p>

<div class="notecard warning">
<p>Unfortunately, <code>next()</code> is asymmetric, but that can’t be helped: It always
<p><strong>Warning:</strong> Unfortunately, <code>next()</code> is asymmetric, but that can’t be helped: It always
sends a value to the currently suspended <code>yield</code>, but returns the operand
of the following <code>yield</code>.</p>
</div>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -265,9 +265,7 @@ <h4 id="await_and_parallelism">await and parallelism</h4>
</p>

<div class="warning">
<h4 id="Error_Handling">Error Handling</h4>

<p>Note that functions <code>concurrentStart</code> and <code>concurrentPromise</code>
<p><strong>Warning:</strong> The functions <code>concurrentStart</code> and <code>concurrentPromise</code>
are not functionally equivalent.</p>

<p>In <code>concurrentStart</code>, if promise <code>fast</code> rejects before promise
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@
- Statement
browser-compat: javascript.statements.with
---
<div class="warning">Use of the <code>with</code> statement is not recommended, as it may
<div class="warning">
<p><strong>Warning:</strong>Use of the <code>with</code> statement is not recommended, as it may
be the source of confusing bugs and compatibility issues. See the "Ambiguity Contra"
paragraph in the "Description" section below for details.</div>
paragraph in the "Description" section below for details.</p>
</div>

<div>{{jsSidebar("Statements")}}</div>

Expand Down