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

In JS docs, use Note: consistently at the start of notes #4504

Merged
merged 5 commits into from
Apr 27, 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 @@ -18,7 +18,7 @@
<p>Several months later, Microsoft released JScript with Internet Explorer 3. It was a mostly-compatible JavaScript work-alike. Several months after that, Netscape submitted JavaScript to <a href="http://www.ecma-international.org/">Ecma International</a>, a European standards organization, which resulted in the first edition of the <a href="/en-US/docs/Glossary/ECMAScript">ECMAScript</a> standard that year. The standard received a significant update as <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript edition 3</a> in 1999, and it has stayed pretty much stable ever since. The fourth edition was abandoned, due to political differences concerning language complexity. Many parts of the fourth edition formed the basis for ECMAScript edition 5, published in December of 2009, and for the 6th major edition of the standard, published in June of 2015.</p>

<div class="note">
<p>Because it is more familiar, we will refer to ECMAScript as "JavaScript" from this point on.</p>
<p><strong>Note:</strong> Because it is more familiar, we will refer to ECMAScript as "JavaScript" from this point on.</p>
</div>

<p>Unlike most programming languages, the JavaScript language has no concept of input or output. It is designed to run as a scripting language in a host environment, and it is up to the host environment to provide mechanisms for communicating with the outside world. The most common host environment is the browser, but JavaScript interpreters can also be found in a huge list of other places, including Adobe Acrobat, Adobe Photoshop, SVG images, Yahoo's Widget engine, server-side environments such as <a href="http://nodejs.org/">Node.js</a>, NoSQL databases like the open source <a href="http://couchdb.apache.org/">Apache CouchDB</a>, embedded computers, complete desktop environments like <a href="http://www.gnome.org/">GNOME</a> (one of the most popular GUIs for GNU/Linux operating systems), and others.</p>
Expand Down Expand Up @@ -155,7 +155,7 @@ <h2 id="Numbers">Numbers</h2>
isFinite(NaN); // false
</pre>

<div class="note">The {{jsxref("Global_Objects/parseInt", "parseInt()")}} and {{jsxref("Global_Objects/parseFloat", "parseFloat()")}} functions parse a string until they reach a character that isn't valid for the specified number format, then return the number parsed up to that point. However the "+" operator converts the string to <code>NaN</code> if there is an invalid character contained within it. Just try parsing the string "10.2abc" with each method by yourself in the console and you'll understand the differences better.</div>
<div class="note"><p><strong>Note:</strong> The {{jsxref("Global_Objects/parseInt", "parseInt()")}} and {{jsxref("Global_Objects/parseFloat", "parseFloat()")}} functions parse a string until they reach a character that isn't valid for the specified number format, then return the number parsed up to that point. However the "+" operator converts the string to <code>NaN</code> if there is an invalid character contained within it. Just try parsing the string "10.2abc" with each method by yourself in the console and you'll understand the differences better.</p></div>

<h2 id="Strings">Strings</h2>

Expand Down Expand Up @@ -466,13 +466,13 @@ <h2 id="Objects">Objects</h2>
</pre>

<div class="note">
<p>Starting in ECMAScript 5, reserved words may be used as object property names "in the buff". This means that they don't need to be "clothed" in quotes when defining object literals. See the ES5 <a href="https://es5.github.io/#x7.6.1">Spec</a>.</p>
<p><strong>Note:</strong> Starting in ECMAScript 5, reserved words may be used as object property names "in the buff". This means that they don't need to be "clothed" in quotes when defining object literals. See the ES5 <a href="https://es5.github.io/#x7.6.1">Spec</a>.</p>
</div>

<p>For more on objects and prototypes see <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">Object.prototype</a>. For an explanation of object prototypes and the object prototype chains see <a href="/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain">Inheritance and the prototype chain</a>.</p>

<div class="note">
<p>Starting in ECMAScript 2015, object keys can be defined by the variable using bracket notation upon being created. <code>{[phoneType]: 12345}</code> is possible instead of just <code>var userPhone = {}; userPhone[phoneType] = 12345</code>.</p>
<p><strong>Note:</strong> Starting in ECMAScript 2015, object keys can be defined by the variable using bracket notation upon being created. <code>{[phoneType]: 12345}</code> is possible instead of just <code>var userPhone = {}; userPhone[phoneType] = 12345</code>.</p>
</div>

<h2 id="Arrays">Arrays</h2>
Expand Down Expand Up @@ -658,9 +658,9 @@ <h2 id="Functions">Functions</h2>
avg(2, 3, 4, 5); // 3.5
</pre>

<div class="note">In the above code, the variable <strong>args</strong> holds all the values that were passed into the function.<br>
<p>In the above code, the variable <strong>args</strong> holds all the values that were passed into the function.<br>
<br>
It is important to note that wherever the rest parameter operator is placed in a function declaration it will store all arguments <em>after</em> its declaration, but not before. <em>i.e. function</em> <em>avg(</em><strong>firstValue, </strong><em>...args)</em> will store the first value passed into the function in the <strong>firstValue</strong> variable and the remaining arguments in <strong>args</strong>. That's another useful language feature but it does lead us to a new problem. The <code>avg()</code> function takes a comma-separated list of arguments — but what if you want to find the average of an array? You could just rewrite the function as follows:</div>
It is important to note that wherever the rest parameter operator is placed in a function declaration it will store all arguments <em>after</em> its declaration, but not before. <em>i.e. function</em> <em>avg(</em><strong>firstValue, </strong><em>...args)</em> will store the first value passed into the function in the <strong>firstValue</strong> variable and the remaining arguments in <strong>args</strong>. That's another useful language feature but it does lead us to a new problem. The <code>avg()</code> function takes a comma-separated list of arguments — but what if you want to find the average of an array? You could just rewrite the function as follows:</p>

<pre class="brush: js">function avgArray(arr) {
var sum = 0;
Expand All @@ -680,11 +680,9 @@ <h2 id="Functions">Functions</h2>

<p>The second argument to <code>apply()</code> is the array to use as arguments; the first will be discussed later on. This emphasizes the fact that functions are objects too.</p>

<div class="note">
<p>You can achieve the same result using the <a href="/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax">spread operator</a> in the function call.</p>

<p>For instance: <code>avg(...numbers)</code></p>
</div>

<h3 id="anonymous_functions">Anonymous functions</h3>

Expand Down Expand Up @@ -757,7 +755,7 @@ <h3 id="recursive_functions">Recursive functions</h3>

<h2 id="Custom_objects">Custom objects</h2>

<div class="note">For a more detailed discussion of object-oriented programming in JavaScript, see <a href="/en-US/docs/Learn/JavaScript/Objects">Introduction to Object-Oriented JavaScript</a>.</div>
<div class="note"><p><strong>Note:</strong> For a more detailed discussion of object-oriented programming in JavaScript, see <a href="/en-US/docs/Learn/JavaScript/Objects">Introduction to Object-Oriented JavaScript</a>.</p></div>

<p>In classic Object Oriented Programming, objects are collections of data and methods that operate on that data. JavaScript is a prototype-based language that contains no class statement, as you'd find in C++ or Java (this is sometimes confusing for programmers accustomed to languages with a class statement). Instead, JavaScript uses functions as classes. Let's consider a person object with first and last name fields. There are two ways in which the name might be displayed: as "first last" or as "last, first". Using the functions and objects that we've discussed previously, we could display the data like this:</p>

Expand Down
2 changes: 1 addition & 1 deletion files/en-us/web/javascript/closures/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ <h2 id="Emulating_private_methods_with_closures">Emulating private methods with
<p>Notice how the two counters maintain their independence from one another. Each closure references a different version of the <code>privateCounter</code> variable through its own closure. Each time one of the counters is called, its lexical environment changes by changing the value of this variable. Changes to the variable value in one closure don't affect the value in the other closure.</p>

<div class="note">
<p>Using closures in this way provides benefits that are normally associated with object-oriented programming. In particular, <em>data hiding</em> and <em>encapsulation</em>.</p>
<p><strong>Note:</strong> Using closures in this way provides benefits that are normally associated with object-oriented programming. In particular, <em>data hiding</em> and <em>encapsulation</em>.</p>
</div>

<h2 id="Closure_Scope_Chain">Closure Scope Chain</h2>
Expand Down
4 changes: 2 additions & 2 deletions files/en-us/web/javascript/data_structures/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ <h3 id="Number_type">Number type</h3>
<p>To check for the largest available value or smallest available value within {{jsxref("Infinity", "±Infinity")}}, you can use the constants {{jsxref("Number.MAX_VALUE")}} or {{jsxref("Number.MIN_VALUE")}}.</p>

<div class="notecard note">
<p><strong>Starting with ECMAScript 2015,</strong> you are also able to check if a number is in the double-precision floating-point number range using {{jsxref("Number.isSafeInteger()")}} as well as {{jsxref("Number.MAX_SAFE_INTEGER")}} and {{jsxref("Number.MIN_SAFE_INTEGER")}}.</p>
<p><strong>Note:</strong> Starting with ECMAScript 2015, you are also able to check if a number is in the double-precision floating-point number range using {{jsxref("Number.isSafeInteger()")}} as well as {{jsxref("Number.MAX_SAFE_INTEGER")}} and {{jsxref("Number.MIN_SAFE_INTEGER")}}.</p>

<p>Beyond this range, integers in JavaScript are not safe anymore and will be a double-precision floating point approximation of the value.</p>
</div>
Expand All @@ -96,7 +96,7 @@ <h3 id="Number_type">Number type</h3>
<p>Although a number often represents only its value, JavaScript provides {{jsxref("Operators", "binary (bitwise) operators")}}.</p>

<div class="notecard note">
<p><strong>Caution:</strong> Although bitwise operators <em>can</em> be used to represent several Boolean values within a single number using <a href="https://en.wikipedia.org/wiki/Mask_%28computing%29">bit masking</a>, this is usually considered a bad practice. JavaScript offers other means to represent a set of Booleans (like an array of Booleans, or an object with Boolean values assigned to named properties). Bit masking also tends to make the code more difficult to read, understand, and maintain.</p>
<p><strong>Note:</strong> Although bitwise operators <em>can</em> be used to represent several Boolean values within a single number using <a href="https://en.wikipedia.org/wiki/Mask_%28computing%29">bit masking</a>, this is usually considered a bad practice. JavaScript offers other means to represent a set of Booleans (like an array of Booleans, or an object with Boolean values assigned to named properties). Bit masking also tends to make the code more difficult to read, understand, and maintain.</p>
</div>

<p>It may be necessary to use such techniques in very constrained environments, like when trying to cope with the limitations of local storage, or in extreme cases (such as when each bit over the network counts). This technique should only be considered when it is the last measure that can be taken to optimize size.</p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ <h3 id="Example">Example</h3>
<p>Here, <code>{ x++; }</code> is the block statement.</p>

<div class="notecard note">
<p><strong>Important</strong>: JavaScript before ECMAScript2015 (6<sup>th</sup> edition)
<p><strong>Note:</strong> JavaScript before ECMAScript2015 (6<sup>th</sup> edition)
<strong>does not</strong> have block scope!  In older JavaScript, variables introduced
within a block are scoped to the containing function or script, and the effects of
setting them persist beyond the block itself. In other words, <em>block statements do
Expand Down Expand Up @@ -181,7 +181,7 @@ <h4 id="Falsy_values">Falsy values</h4>
conditional statement.</p>

<div class="notecard note">
<p><strong>Caution:</strong> Do not confuse the primitive boolean values
<p><strong>Note:</strong> Do not confuse the primitive boolean values
<code>true</code> and <code>false</code> with the true and false values of the
{{jsxref("Boolean")}} object!</p>

Expand Down Expand Up @@ -437,7 +437,7 @@ <h4 id="The_catch_block">The <code>catch</code> block</h4>
</pre>

<div class="notecard note">
<p><strong>Best practice:</strong> When logging errors to the console inside
<p><strong>Note:</strong> When logging errors to the console inside
a <code>catch</code> block, using <code>console.error()</code> rather than
<code>console.log()</code> is advised for debugging. It formats the message as an
error, and adds it to the list of error messages generated by the page. </p>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ <h3 id="Defining_a_class">Defining a class</h3>
<p>JavaScript follows a similar model, but does not have a class definition separate from the constructor. Instead, you define a constructor function to create objects with a particular initial set of properties and values. Any JavaScript function can be used as a constructor. You use the <code>new</code> operator with a constructor function to create a new object.</p>

<div class="notecard note">
<p>Note that ECMAScript 2015 introduces a <a href="/en-US/docs/Web/JavaScript/Reference/Classes">class declaration</a>:</p>
<p><strong>Note:</strong> ECMAScript 2015 introduces a <a href="/en-US/docs/Web/JavaScript/Reference/Classes">class declaration</a>:</p>

<blockquote>
<p>JavaScript classes, introduced in ECMAScript 2015, are primarily syntactical sugar over JavaScript's existing prototype-based inheritance. The class syntax <em>does not</em> introduce a new object-oriented inheritance model to JavaScript.</p>
Expand Down Expand Up @@ -592,7 +592,7 @@ <h3 id="Determining_instance_relationships">Determining instance relationships</
}
</pre>

<div class="note"><strong>Note:</strong> The implementation above checks the type of the object against "xml" in order to work around a quirk of how XML objects are represented in recent versions of JavaScript. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=634150">bug 634150</a> if you want the nitty-gritty details.</div>
<div class="note"><p><strong>Note:</strong> The implementation above checks the type of the object against "xml" in order to work around a quirk of how XML objects are represented in recent versions of JavaScript. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=634150">bug 634150</a> if you want the nitty-gritty details.</p></div>

<p>Using the instanceOf function defined above, these expressions are true:</p>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -349,7 +349,7 @@ <h3 id="Comparison_operators">Comparison operators</h3>
</table>

<div class="note">
<p><strong>Note: </strong>(<strong>=&gt;</strong>) is not an operator, but the notation
<p><strong>Note:</strong> <code>=&gt;</code> is not an operator, but the notation
for <a href="/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">Arrow
functions</a>.</p>
</div>
Expand Down
2 changes: 1 addition & 1 deletion files/en-us/web/javascript/guide/functions/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -470,7 +470,7 @@ <h2 id="Closures">Closures</h2>
</pre>

<div class="notecard note">
<p><strong>Caution:</strong> There are a number of pitfalls to watch out for when using closures!</p>
<p><strong>Note:</strong> There are a number of pitfalls to watch out for when using closures!</p>

<p>If an enclosed function defines a variable with the same name as a variable in the outer scope, then there is no way to refer to the variable in the outer scope again.  (The inner scope variable "overrides" the outer one, until the program exits the inner scope.)</p>

Expand Down
Loading