From 9791f3ab926e5368386f88455f802248a6cd5b36 Mon Sep 17 00:00:00 2001 From: wbamberg Date: Thu, 29 Apr 2021 23:39:29 -0700 Subject: [PATCH] Make warnings consistent in the JS docs (#4609) Co-authored-by: Will <> --- .../web/javascript/guide/grammar_and_types/index.html | 2 +- .../inheritance_and_the_prototype_chain/index.html | 2 +- .../en-us/web/javascript/reference/classes/index.html | 2 +- .../the_legacy_iterator_protocol/index.html | 2 +- .../reference/functions/arguments/callee/index.html | 2 +- .../reference/global_objects/array/join/index.html | 2 +- .../reference/global_objects/array/values/index.html | 2 +- .../reference/global_objects/error/index.html | 4 ++-- .../reference/global_objects/escape/index.html | 4 ++-- .../global_objects/intl/locale/calendar/index.html | 4 +++- .../global_objects/intl/locale/collation/index.html | 2 +- .../global_objects/object/__definegetter__/index.html | 2 +- .../global_objects/object/__definesetter__/index.html | 2 +- .../reference/global_objects/parseint/index.html | 10 +++++++--- .../reference/global_objects/promise/catch/index.html | 2 +- .../reference/global_objects/string/anchor/index.html | 2 +- .../global_objects/string/localecompare/index.html | 3 +-- .../reference/global_objects/string/split/index.html | 2 +- .../global_objects/typedarray/values/index.html | 2 +- .../reference/global_objects/unescape/index.html | 4 ++-- .../webassembly/instance/instance/index.html | 2 +- .../global_objects/webassembly/instantiate/index.html | 2 +- .../webassembly/module/module/index.html | 2 +- .../javascript/reference/lexical_grammar/index.html | 2 +- .../reference/operators/object_initializer/index.html | 2 +- .../javascript/reference/operators/yield/index.html | 2 +- .../reference/statements/async_function/index.html | 4 +--- .../javascript/reference/statements/with/index.html | 6 ++++-- 28 files changed, 42 insertions(+), 37 deletions(-) diff --git a/files/en-us/web/javascript/guide/grammar_and_types/index.html b/files/en-us/web/javascript/guide/grammar_and_types/index.html index c1b9d1c0b99a428..f564f33b65f2a85 100644 --- a/files/en-us/web/javascript/guide/grammar_and_types/index.html +++ b/files/en-us/web/javascript/guide/grammar_and_types/index.html @@ -495,7 +495,7 @@

Object literals

An object literal is a list of zero or more pairs of property names and associated values of an object, enclosed in curly braces ({}).

-

Note: 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 { will be interpreted as the beginning of a block.

+

Warning: 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 { will be interpreted as the beginning of a block.

The following is an example of an object literal. The first element of the car object defines a property, myCar, and assigns to it a new string, "Saturn"; the second element, the getCar property, is immediately assigned the result of invoking the function (carTypes("Honda")); the third element, the special property, uses an existing variable (sales).

diff --git a/files/en-us/web/javascript/inheritance_and_the_prototype_chain/index.html b/files/en-us/web/javascript/inheritance_and_the_prototype_chain/index.html index 0ceeba433bf90a4..0b10d23052a6abc 100644 --- a/files/en-us/web/javascript/inheritance_and_the_prototype_chain/index.html +++ b/files/en-us/web/javascript/inheritance_and_the_prototype_chain/index.html @@ -378,7 +378,7 @@

Summary of methods

#1: New initialization

-

One misfeature that is often used is to extend Object.prototype or one of the other built-in prototypes.

+

Warning: One misfeature that is often used is to extend Object.prototype or one of the other built-in prototypes.

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

diff --git a/files/en-us/web/javascript/reference/classes/index.html b/files/en-us/web/javascript/reference/classes/index.html index 3b877ee9ece780e..b07e29869553180 100644 --- a/files/en-us/web/javascript/reference/classes/index.html +++ b/files/en-us/web/javascript/reference/classes/index.html @@ -217,7 +217,7 @@

Instance properties

Field declarations

-

Public and private field declarations are an experimental feature (stage 3) proposed at TC39, the JavaScript standards committee. Support in browsers is limited, but the feature can be used through a build step with systems like Babel.

+

Warning: Public and private field declarations are an experimental feature (stage 3) proposed at TC39, the JavaScript standards committee. Support in browsers is limited, but the feature can be used through a build step with systems like Babel.

Public field declarations

diff --git a/files/en-us/web/javascript/reference/deprecated_and_obsolete_features/the_legacy_iterator_protocol/index.html b/files/en-us/web/javascript/reference/deprecated_and_obsolete_features/the_legacy_iterator_protocol/index.html index 084f4b74ec2b3d8..7096ea7ee74cf32 100644 --- a/files/en-us/web/javascript/reference/deprecated_and_obsolete_features/the_legacy_iterator_protocol/index.html +++ b/files/en-us/web/javascript/reference/deprecated_and_obsolete_features/the_legacy_iterator_protocol/index.html @@ -10,7 +10,7 @@ ---
{{jsSidebar("More")}}
-
Non-standard. The legacy iterator protocol was a SpiderMonkey-specific feature, which is removed in Firefox 58+. For future-facing usages, consider using for..of loops and the iterator protocol.
+

Warning: The legacy iterator protocol was a SpiderMonkey-specific feature, which is removed in Firefox 58+. For future-facing usages, consider using for..of loops and the iterator protocol.

The deprecated Firefox-only iterator protocol

diff --git a/files/en-us/web/javascript/reference/functions/arguments/callee/index.html b/files/en-us/web/javascript/reference/functions/arguments/callee/index.html index 6a1df4924c83ee7..ab63ad63719c441 100644 --- a/files/en-us/web/javascript/reference/functions/arguments/callee/index.html +++ b/files/en-us/web/javascript/reference/functions/arguments/callee/index.html @@ -17,7 +17,7 @@

Description

callee is a property of the arguments 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").

-
Warning: The 5th edition of ECMAScript (ES5) forbids use of arguments.callee() in strict mode. Avoid using arguments.callee() by either giving function expressions a name or use a function declaration where a function must call itself.
+

Warning: The 5th edition of ECMAScript (ES5) forbids use of arguments.callee() in strict mode. Avoid using arguments.callee() by either giving function expressions a name or use a function declaration where a function must call itself.

Why was arguments.callee removed from ES5 strict mode?

diff --git a/files/en-us/web/javascript/reference/global_objects/array/join/index.html b/files/en-us/web/javascript/reference/global_objects/array/join/index.html index 726c0a91f1529f8..1331f43af4f4ec9 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/join/index.html +++ b/files/en-us/web/javascript/reference/global_objects/array/join/index.html @@ -46,7 +46,7 @@

Description

The string conversions of all array elements are joined into one string.

-

If an element is undefined, null or an empty array +

Warning: If an element is undefined, null or an empty array [], it is converted to an empty string.

diff --git a/files/en-us/web/javascript/reference/global_objects/array/values/index.html b/files/en-us/web/javascript/reference/global_objects/array/values/index.html index 11514fcd277e4b4..ac1640de59216ea 100644 --- a/files/en-us/web/javascript/reference/global_objects/array/values/index.html +++ b/files/en-us/web/javascript/reference/global_objects/array/values/index.html @@ -59,7 +59,7 @@

Iteration using .next()

iteraror.next().value; // undefined
-

One-use: the array iterator object is one use or temporary object

+

Warning: The array iterator object is one use or temporary object

example:

diff --git a/files/en-us/web/javascript/reference/global_objects/error/index.html b/files/en-us/web/javascript/reference/global_objects/error/index.html index f5947d755ce0b49..280f6328d7d2222 100644 --- a/files/en-us/web/javascript/reference/global_objects/error/index.html +++ b/files/en-us/web/javascript/reference/global_objects/error/index.html @@ -119,7 +119,7 @@

Custom Error Types

ES6 Custom Error Class

-

Versions of Babel prior to 7 can handle CustomError class methods, but only when they are declared with Object.defineProperty(). Otherwise, old versions of Babel and other transpilers will not correctly handle the following code without additional configuration.

+

Warning: Versions of Babel prior to 7 can handle CustomError class methods, but only when they are declared with Object.defineProperty(). Otherwise, old versions of Babel and other transpilers will not correctly handle the following code without additional configuration.

@@ -155,7 +155,7 @@

ES6 Custom Error Class

ES5 Custom Error Object

-

All browsers include the CustomError constructor in the stack trace when using a prototypal declaration.

+

Warning: All browsers include the CustomError constructor in the stack trace when using a prototypal declaration.

function CustomError(foo, message, fileName, lineNumber) {
diff --git a/files/en-us/web/javascript/reference/global_objects/escape/index.html b/files/en-us/web/javascript/reference/global_objects/escape/index.html
index 67c146dddc57081..06fec0494acd709 100644
--- a/files/en-us/web/javascript/reference/global_objects/escape/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/escape/index.html
@@ -9,10 +9,10 @@
 ---
 
{{jsSidebar("Objects")}}

 
-
Warning: Although escape() is not
+
Warning: Although escape() is not
   strictly deprecated (as in "removed from the Web standards"), it is defined in Annex
-    B of the ECMA-262 standard, whose introduction states:
+    B of the ECMA-262 standard, whose introduction states:

 
   
… 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
diff --git a/files/en-us/web/javascript/reference/global_objects/intl/locale/calendar/index.html b/files/en-us/web/javascript/reference/global_objects/intl/locale/calendar/index.html
index 1d6da088fe14bd2..730477fc204d66b 100644
--- a/files/en-us/web/javascript/reference/global_objects/intl/locale/calendar/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/intl/locale/calendar/index.html
@@ -105,7 +105,9 @@ 
Unicode calendar keys

   
   
    
-    
The islamicc calendar key has been deprecated. Please use islamic-civil.

+    

+      
Warning: The islamicc calendar key has been deprecated. Please use islamic-civil.

+    

 
     
islamicc

    
diff --git a/files/en-us/web/javascript/reference/global_objects/intl/locale/collation/index.html b/files/en-us/web/javascript/reference/global_objects/intl/locale/collation/index.html
index 4c5d4fcd75f2eb5..f6697c4ef6bc53a 100644
--- a/files/en-us/web/javascript/reference/global_objects/intl/locale/collation/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/intl/locale/collation/index.html
@@ -47,7 +47,7 @@ 
Valid collation types

 		
 			
 				

-					
The direct collation type has been deprected. Do not use.

+					
Warning: The direct collation type has been deprected. Do not use.

 				

 				
direct

 			
diff --git a/files/en-us/web/javascript/reference/global_objects/object/__definegetter__/index.html b/files/en-us/web/javascript/reference/global_objects/object/__definegetter__/index.html
index 9df4312a8ff4bed..5e55d72f8b5d85f 100644
--- a/files/en-us/web/javascript/reference/global_objects/object/__definegetter__/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/object/__definegetter__/index.html
@@ -12,7 +12,7 @@
 
{{JSRef}}

 
 

-  
This feature is deprecated in favor of defining getters using the Warning: This feature is deprecated in favor of defining getters using the object
       initializer syntax or the {{jsxref("Object.defineProperty()")}} API. While this
     feature is widely implemented, it is only described in the {{JSRef}}

 
 

-  
This feature is deprecated in favor of defining setters using the Warning: This feature is deprecated in favor of defining setters using the object
       initializer syntax or the {{jsxref("Object.defineProperty()")}} API.

 
diff --git a/files/en-us/web/javascript/reference/global_objects/parseint/index.html b/files/en-us/web/javascript/reference/global_objects/parseint/index.html
index 4090d7b658d2a59..281d9a921651171 100644
--- a/files/en-us/web/javascript/reference/global_objects/parseint/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/parseint/index.html
@@ -38,8 +38,12 @@ 
Parameters

     string. Be careful—this does not
     default to 10! If the radix value is not of the Number type
     it will be coerced to a Number
-  
The description below explains
-    in more detail what happens when radix is not provided.

+  

+    
Warning: The description below explains
+    in more detail what happens when radix is not provided.
+    

+    

+  

 
 
 
Return value

@@ -113,7 +117,7 @@ 
Description

   thatNumber.toString(radix).

 
 

-  
{{jsxref("BigInt")}} Warning: parseInt converts a
+  
Warning: parseInt converts a
     {{jsxref("BigInt")}} to a {{jsxref("Number")}} and loses precision in the process.
     This is because trailing non-numeric values, including "n", are
     discarded.

diff --git a/files/en-us/web/javascript/reference/global_objects/promise/catch/index.html b/files/en-us/web/javascript/reference/global_objects/promise/catch/index.html
index fd118934cbc8915..a4f2645cd8a0e55 100644
--- a/files/en-us/web/javascript/reference/global_objects/promise/catch/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/promise/catch/index.html
@@ -56,7 +56,7 @@ 
Return value

   {{jsxref("Promise")}}.

 
 

-  
Note the examples below are throwing instances of Warning: The examples below are throwing instances of Error. 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
diff --git a/files/en-us/web/javascript/reference/global_objects/string/anchor/index.html b/files/en-us/web/javascript/reference/global_objects/string/anchor/index.html
index 7dff053eb65c2bc..0f3b17bb07d20e9 100644
--- a/files/en-us/web/javascript/reference/global_objects/string/anchor/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/string/anchor/index.html
@@ -18,7 +18,7 @@
   </a> end tag.

 
 

-  
Don't use this method. Use DOM
+  
Warning: Don't use this method. Use DOM
       APIs instead. Also, the HTML specification no longer allows the
     {{HTMLElement("a")}} element to have a name attribute, so this method
     doesn't even create valid markup.

diff --git a/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.html b/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.html
index 7dcab8e47aa968e..ee968eb7b421280 100644
--- a/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/string/localecompare/index.html
@@ -69,8 +69,7 @@ 
Description

 
 
 

-  
Do NOT rely on exact return values of -1 or 1!
-    

+  
Warning: Do not rely on exact return values of -1 or 1!

 
   
Negative and positive integer results vary between browsers (as well as between
     browser versions) because the W3C specification only mandates negative and positive
diff --git a/files/en-us/web/javascript/reference/global_objects/string/split/index.html b/files/en-us/web/javascript/reference/global_objects/string/split/index.html
index 0d3a9ea3d66f928..5576594b8edfd14 100644
--- a/files/en-us/web/javascript/reference/global_objects/string/split/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/string/split/index.html
@@ -220,7 +220,7 @@ 
Reversing a String using split()

 
 

-  
This is not a robust way to reverse a string:

+  
Warning: This is not a robust way to reverse a string:

 
   
const str = 'asdfghjkl'
 const strReverse = str.split('').reverse().join('')
diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.html b/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.html
index cf29271805f77a2..324627ab2db65e2 100644
--- a/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/typedarray/values/index.html
@@ -57,7 +57,7 @@ 
Iteration using .next()

 iteraror.next().value;         // undefined 

 
 

-  
One-use: the array iterator object is one use or temporary object

+  
Warning: One-use: the array iterator object is one use or temporary object

 

 
 
example:

diff --git a/files/en-us/web/javascript/reference/global_objects/unescape/index.html b/files/en-us/web/javascript/reference/global_objects/unescape/index.html
index 9193feb8e6ec89d..515155e882a2530 100644
--- a/files/en-us/web/javascript/reference/global_objects/unescape/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/unescape/index.html
@@ -9,10 +9,10 @@
 ---
 
{{jsSidebar("Objects")}}

 
-
Warning: Although unescape() is not strictly deprecated
+
Warning: Although unescape() is not strictly deprecated
   (as in "removed from the Web standards"), it is defined in Annex
-    B of the ECMA-262 standard, whose introduction states:
+    B of the ECMA-262 standard, whose introduction states:

   
… 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. …

diff --git a/files/en-us/web/javascript/reference/global_objects/webassembly/instance/instance/index.html b/files/en-us/web/javascript/reference/global_objects/webassembly/instance/instance/index.html
index 96f7f1d22595766..e42763b81d5602e 100644
--- a/files/en-us/web/javascript/reference/global_objects/webassembly/instance/instance/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/webassembly/instance/instance/index.html
@@ -17,7 +17,7 @@
 
Syntax

 
 

-  
Important: Since instantiation for large modules can be expensive,
+  
Warning: Since instantiation for large modules can be expensive,
     developers should only use the Instance() constructor when synchronous
     instantiation is absolutely required; the asynchronous
     {{jsxref("WebAssembly.instantiateStreaming()")}} method should be used at all other
diff --git a/files/en-us/web/javascript/reference/global_objects/webassembly/instantiate/index.html b/files/en-us/web/javascript/reference/global_objects/webassembly/instantiate/index.html
index 04f0b2c631ecf7b..c63bb903788e28d 100644
--- a/files/en-us/web/javascript/reference/global_objects/webassembly/instantiate/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/webassembly/instantiate/index.html
@@ -30,7 +30,7 @@
 
 
 

-  
Important: This method is not the most efficient way of fetching and
+  
Warning: 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,
diff --git a/files/en-us/web/javascript/reference/global_objects/webassembly/module/module/index.html b/files/en-us/web/javascript/reference/global_objects/webassembly/module/module/index.html
index 078af52d6128436..16f872722e6071d 100644
--- a/files/en-us/web/javascript/reference/global_objects/webassembly/module/module/index.html
+++ b/files/en-us/web/javascript/reference/global_objects/webassembly/module/module/index.html
@@ -24,7 +24,7 @@
 
Syntax

 
 

-  
Important: Since compilation for large modules can be expensive,
+  
Warning: Since compilation for large modules can be expensive,
     developers should only use the Module() constructor when synchronous
     compilation is absolutely required; the asynchronous
     {{jsxref("WebAssembly.compileStreaming()")}} method should be used at all other times.
diff --git a/files/en-us/web/javascript/reference/lexical_grammar/index.html b/files/en-us/web/javascript/reference/lexical_grammar/index.html
index d3927e2ec9ddcec..5bb5327f0c20780 100644
--- a/files/en-us/web/javascript/reference/lexical_grammar/index.html
+++ b/files/en-us/web/javascript/reference/lexical_grammar/index.html
@@ -227,7 +227,7 @@ 
Hashbang comments

 

 
 

-
Although BOM 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.

+
Warning: Although BOM 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.

 

 
 
You must only use the #! comment style to specify a JavaScript interpreter. In all other cases just use a // comment (or mulitiline comment).

diff --git a/files/en-us/web/javascript/reference/operators/object_initializer/index.html b/files/en-us/web/javascript/reference/operators/object_initializer/index.html
index 272945428320515..e552e0364530da5 100644
--- a/files/en-us/web/javascript/reference/operators/object_initializer/index.html
+++ b/files/en-us/web/javascript/reference/operators/object_initializer/index.html
@@ -234,7 +234,7 @@ 
Spread properties

 // Object { foo: "baz", x: 42, y: 13 }
-

Note that {{jsxref("Object.assign()")}} triggers setters, whereas the spread operator doesn't!

+

Warning: Note that {{jsxref("Object.assign()")}} triggers setters, whereas the spread operator doesn't!

Prototype mutation

diff --git a/files/en-us/web/javascript/reference/operators/yield/index.html b/files/en-us/web/javascript/reference/operators/yield/index.html index 30b5b7a4f64575d..b3945a9c66d6a6c 100644 --- a/files/en-us/web/javascript/reference/operators/yield/index.html +++ b/files/en-us/web/javascript/reference/operators/yield/index.html @@ -84,7 +84,7 @@

Description

generators offer enormous power and control.

-

Unfortunately, next() is asymmetric, but that can’t be helped: It always +

Warning: Unfortunately, next() is asymmetric, but that can’t be helped: It always sends a value to the currently suspended yield, but returns the operand of the following yield.

diff --git a/files/en-us/web/javascript/reference/statements/async_function/index.html b/files/en-us/web/javascript/reference/statements/async_function/index.html index 43c8c4f2828c94d..7a987823b03926a 100644 --- a/files/en-us/web/javascript/reference/statements/async_function/index.html +++ b/files/en-us/web/javascript/reference/statements/async_function/index.html @@ -265,9 +265,7 @@

await and parallelism

-

Error Handling

- -

Note that functions concurrentStart and concurrentPromise +

Warning: The functions concurrentStart and concurrentPromise are not functionally equivalent.

In concurrentStart, if promise fast rejects before promise diff --git a/files/en-us/web/javascript/reference/statements/with/index.html b/files/en-us/web/javascript/reference/statements/with/index.html index 3ed223f706a469d..f4d6e6632ac490e 100644 --- a/files/en-us/web/javascript/reference/statements/with/index.html +++ b/files/en-us/web/javascript/reference/statements/with/index.html @@ -8,9 +8,11 @@ - Statement browser-compat: javascript.statements.with --- -

Use of the with statement is not recommended, as it may +
+

Warning:Use of the with 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.

+ paragraph in the "Description" section below for details.

+
{{jsSidebar("Statements")}}