Merge pull request BonsaiDen#98 from XP1/master

Fix a lot of English grammar mistakes. Include English recommendations.

Author: BonsaiDen

doc/en/array/constructor.md

@@ -11,10 +11,10 @@ when creating new arrays.
     new Array(3); // Result: []
     new Array('3') // Result: ['3']
 
-In cases when there is only one argument passed to the `Array` constructor,
-and that argument is a `Number`, the constructor will return a new *sparse* 
+In cases when there is only one argument passed to the `Array` constructor
+and when that argument is a `Number`, the constructor will return a new *sparse* 
 array with the `length` property set to the value of the argument. It should be 
-noted that **only** the `length` property of the new array will be set this way, 
+noted that **only** the `length` property of the new array will be set this way; 
 the actual indexes of the array will not be initialized. 
 
     var arr = new Array(3);

doc/en/array/general.md

@@ -1,15 +1,15 @@
 ## Array Iteration and Properties
 
 Although arrays in JavaScript are objects, there are no good reasons to use
-the [`for in loop`](#object.forinloop) in for iteration on them. In fact there 
+the [`for in loop`](#object.forinloop) in for iteration on them. In fact, there 
 are a number of good reasons **against** the use of `for in` on arrays.
 
 > **Note:** JavaScript arrays are **not** *associative arrays*. JavaScript only 
 > has [objects](#object.general) for mapping keys to values. And while associative 
 > arrays **preserve** order, objects **do not**.
 
-Since the `for in` loop enumerates all the properties that are on the prototype 
-chain and the only way to exclude those properties is to use 
+Because the `for in` loop enumerates all the properties that are on the prototype 
+chain and because the only way to exclude those properties is to use 
 [`hasOwnProperty`](#object.hasownproperty), it is already up to **twenty times** 
 slower than a normal `for` loop.
 
@@ -23,7 +23,7 @@ to use the classic `for` loop.
         console.log(list[i]);
     }
 
-There is one extra catch in the above example, that is the caching of the 
+There is one extra catch in the above example, which is the caching of the 
 length of the array via `l = list.length`.
 
 Although the `length` property is defined on the array itself, there is still an
@@ -52,7 +52,7 @@ does not have any effect on the array.
 
 ### In Conclusion
 
-For the best performance it is recommended to always use the plain `for` loop
+For the best performance, it is recommended to always use the plain `for` loop
 and cache the `length` property. The use of `for in` on an array is a sign of
 badly written code that is prone to bugs and bad performance. 
 

doc/en/core/eval.md

@@ -11,8 +11,8 @@ The `eval` function will execute a string of JavaScript code in the local scope.
     test(); // 3
     foo; // 1
 
-But `eval` only executes in local scope when it is being called **directly** *and* 
-the name of the called function is actually `eval`.
+However, `eval` only executes in the local scope when it is being called
+**directly** *and* when the name of the called function is actually `eval`.
 
     var foo = 1;
     function test() {
@@ -35,14 +35,13 @@ in the global scope since `eval` is not being called directly in that case.
 
 ### Security Issues
 
-`eval` also is a security problem as it executes **any** code given to it,
+`eval` also is a security problem. Because it executes **any** code given to it,
 it should **never** be used with strings of unknown or untrusted origins.
 
 ### In Conclusion
 
-`eval` should never be used, any code that makes use of it is to be questioned in
+`eval` should never be used. Any code that makes use of it is to be questioned in
 its workings, performance and security. In case something requires `eval` in 
-order to work, its design is to be questioned and should **not** be used in the 
-first place, a *better design* should be used, that does not require the use of 
-`eval`. 
+order to work, it should **not** be used in the first place.
+A *better design* should be used, that does not require the use of `eval`.
 

doc/en/core/semicolon.md

@@ -1,10 +1,10 @@
 ## Automatic Semicolon Insertion
 
 Although JavaScript has C style syntax, it does **not** enforce the use of
-semicolons in the source code, it is possible to omit them.
+semicolons in the source code, so it is possible to omit them.
 
-But JavaScript is not a semicolon-less language, it in fact needs the 
-semicolons in order to understand the source code. Therefore the JavaScript
+JavaScript is not a semicolon-less language. In fact, it needs the 
+semicolons in order to understand the source code. Therefore, the JavaScript
 parser **automatically** inserts them whenever it encounters a parse
 error due to a missing semicolon.
 
@@ -19,7 +19,7 @@ Insertion happens, and the parser tries again.
     test()
 
 The automatic insertion of semicolon is considered to be one of **biggest**
-design flaws in the language, as it *can* change the behavior of code.
+design flaws in the language because it *can* change the behavior of code.
 
 ### How it Works
 
@@ -87,7 +87,7 @@ Below is the result of the parser's "guessing" game.
 > which are followed by a new line, while this is not neccessarily the fault of 
 > the automatic semicolon insertion, it can still be an unwanted side-effect. 
 
-The parser drastically changed the behavior of the code above, in certain cases
+The parser drastically changed the behavior of the code above. In certain cases,
 it does the **wrong thing**.
 
 ### Leading Parenthesis
@@ -106,9 +106,9 @@ the above will yield a `TypeError` stating that `undefined is not a function`.
 
 ### In Conclusion
 
-It is highly recommended to **never** omit semicolons, it is also advocated to 
+It is highly recommended to **never** omit semicolons; it is also advocated to 
 keep braces on the same line with their corresponding statements and to never omit 
 them for one single-line `if` / `else` statements. Both of these measures will 
-not only improve the consistency of the code, they will also prevent the 
+not only improve the consistency of the code, but they will also prevent the 
 JavaScript parser from changing its behavior.
 

doc/en/core/undefined.md

@@ -7,9 +7,9 @@ being `undefined`.
 
 `undefined` is a type with exactly one value: `undefined`.
 
-The language also defines a global variable that has the value of `undefined`,
-this variable is also called `undefined`. But this variable is **not** a constant,
-nor is it a keyword of the language. This means that its *value* can be easily 
+The language also defines a global variable that has the value of `undefined`;
+this variable is also called `undefined`. However, this variable is **neither** a constant
+nor a keyword of the language. This means that its *value* can be easily 
 overwritten.
 
 > **ES5 Note:** `undefined` in ECMAScript 5 is **no longer** *writable* in strict
@@ -31,12 +31,12 @@ Since the global variable `undefined` only holds a copy of the actual *value* of
 `undefined`, assigning a new value to it does **not** change the value of the 
 *type* `undefined`.
 
-Still, in order to compare something against the value of `undefined` it is
+Still, in order to compare something against the value of `undefined`, it is
 necessary to retrieve the value of `undefined` first.
 
 In order to protect code against a possible overwritten `undefined` variable, a 
 common technique used is to add an additional parameter to an
-[anonymous wrapper](#function.scopes), that gets no argument passed to it.
+[anonymous wrapper](#function.scopes) that gets no argument passed to it.
 
     var undefined = 123;
     (function(something, foo, undefined) {
@@ -55,8 +55,8 @@ wrapper.
 
     })('Hello World', 42);
 
-The only difference being here, that this version results in 4 more bytes being
-used in case it is minified and there is no other `var` statement inside the
+The only difference here is that this version results in 4 more bytes being
+used in case it is minified, and there is no other `var` statement inside the
 anonymous wrapper.
 
 ### Uses of `null`
@@ -66,7 +66,7 @@ the sense of a traditional *null*, the actual `null` (both a literal and a type)
 is more or less just another data type.
 
 It is used in some JavaScript internals (like declaring the end of the
-prototype chain by setting `Foo.prototype = null`), but in almost all cases it
+prototype chain by setting `Foo.prototype = null`), but in almost all cases, it
 can be replaced by `undefined`.
 
 

doc/en/function/arguments.md

@@ -23,8 +23,8 @@ The code below will return a new `Array` containing all the elements of the
 
     Array.prototype.slice.call(arguments);
 
-This conversion is **slow**, it is **not recommended** to use it in performance 
-critical sections of code.
+Because this conversion is **slow**, it is **not recommended** to use it in
+performance-critical sections of code.
 
 ### Passing Arguments
 
@@ -59,7 +59,7 @@ wrappers.
 ### Formal Parameters and Arguments Indices
 
 The `arguments` object creates *getter* and *setter* functions for both its 
-properties as well as the function's formal parameters.
+properties, as well as the function's formal parameters.
 
 As a result, changing the value of a formal parameter will also change the value
 of the corresponding property on the `arguments` object, and the other way around.
@@ -105,8 +105,8 @@ modern JavaScript engines. That case is the use of `arguments.callee`.
 
 In the above code, `foo` can no longer be a subject to [inlining][1] since it 
 needs to know about both itself and its caller. This not only defeats possible 
-performance gains that would arise from inlining, it also breaks encapsulation
-since the function may now be dependent on a specific calling context.
+performance gains that would arise from inlining, but it also breaks encapsulation
+because the function may now be dependent on a specific calling context.
 
 It is **highly recommended** to **never** make use of `arguments.callee` or any of 
 its properties.

doc/en/function/closures.md

@@ -1,8 +1,8 @@
 ## Closures and References
 
-One of JavaScript's most powerful features is the availability of *closures*,
-this means that scopes **always** keep access to the outer scope they were
-defined in. Since the only scoping that JavaScript has is 
+One of JavaScript's most powerful features is the availability of *closures*.
+With closures, scopes **always** keep access to the outer scope, in which they
+were defined. Since the only scoping that JavaScript has is 
 [function scope](#function.scopes), all functions, by default, act as closures.
 
 ### Emulating private variables
@@ -24,7 +24,7 @@ defined in. Since the only scoping that JavaScript has is
     foo.increment();
     foo.get(); // 5
 
-Here, `Counter` returns **two** closures. The function `increment` as well as 
+Here, `Counter` returns **two** closures: the function `increment` as well as 
 the function `get`. Both of these functions keep a **reference** to the scope of 
 `Counter` and, therefore, always keep access to the `count` variable that was 
 defined in that very scope.
@@ -58,8 +58,8 @@ copying the value of the loops index variable.
 The above will **not** output the numbers `0` through `9`, but will simply print
 the number `10` ten times.
 
-The *anonymous* function keeps a **reference** to `i` and at the time 
-`console.log` gets called, the `for loop` has already finished and the value of 
+The *anonymous* function keeps a **reference** to `i`. At the time 
+`console.log` gets called, the `for loop` has already finished, and the value of 
 `i` as been set to `10`.
 
 In order to get the desired behavior, it is necessary to create a **copy** of 
@@ -84,8 +84,8 @@ argument and will receive a copy of the **value** of `i` as its parameter `e`.
 The anonymous function that gets passed to `setTimeout` now has a reference to 
 `e`, whose value does **not** get changed by the loop.
 
-There is another possible way of achieving this; that is to return a function 
-from the anonymous wrapper, that will then have the same behavior as the code 
+There is another possible way of achieving this, which is to return a function 
+from the anonymous wrapper that will then have the same behavior as the code 
 above.
 
     for(var i = 0; i < 10; i++) {

doc/en/function/constructors.md

@@ -24,7 +24,7 @@ implicitly returns the value of `this` - the new object.
 The above calls `Foo` as constructor and sets the `prototype` of the newly
 created object to `Foo.prototype`.
 
-In case of an explicit `return` statement the function returns the value 
+In case of an explicit `return` statement, the function returns the value 
 specified that statement, **but only** if the return value is an `Object`.                                     
 
     function Bar() {
@@ -73,7 +73,7 @@ explicitly return a value.
     Bar();
 
 Both calls to `Bar` return the exact same thing, a newly create object which
-has a property called `method` on it, that is a 
+has a property called `method` on it, which is a 
 [Closure](#function.closures).
 
 It is also to note that the call `new Bar()` does **not** affect the prototype 
@@ -86,7 +86,7 @@ not using the `new` keyword.
 
 ### Creating New Objects via Factories
 
-An often made recommendation is to **not** use `new` since forgetting its use
+An often made recommendation is to **not** use `new` because forgetting its use
 may lead to bugs.
 
 In order to create new object, one should rather use a factory and construct a 

doc/en/function/general.md

@@ -25,7 +25,7 @@ This example assigns the unnamed and *anonymous* function to the variable `foo`.
     foo(); // this raises a TypeError
     var foo = function() {};
 
-Due to the fact that `var` is a declaration, that hoists the variable name `foo` 
+Due to the fact that `var` is a declaration that hoists the variable name `foo` 
 before the actual execution of the code starts, `foo` is already defined when 
 the script gets executed.
 
@@ -41,8 +41,8 @@ Another special case is the assignment of named functions.
     }
     bar(); // ReferenceError
 
-Here `bar` is not available in the outer scope, since the function only gets
-assigned to `foo`; however, inside of `bar` it is available. This is due to 
+Here, `bar` is not available in the outer scope, since the function only gets
+assigned to `foo`; however, inside of `bar`, it is available. This is due to 
 how [name resolution](#function.scopes) in JavaScript works, the name of the 
 function is *always* made available in the local scope of the function itself.
 

doc/en/function/scopes.md

@@ -16,7 +16,7 @@ is in the language is *function scope*.
 > **not** as an object literal. This, in conjunction with 
 > [automatic insertion of semicolons](#core.semicolon), can lead to subtle errors.
 
-There are also no distinct namespaces in JavaScript, that means that everything 
+There are also no distinct namespaces in JavaScript, which means that everything 
 gets defined in one *globally shared* namespace.
 
 Each time a variable is referenced, JavaScript will traverse upwards through all 
@@ -32,10 +32,10 @@ still has not found the requested name, it will raise a `ReferenceError`.
     var foo = '42'
 
 The above two scripts do **not** have the same effect. Script A defines a 
-variable called `foo` in the *global* scope and script B defines a `foo` in the
+variable called `foo` in the *global* scope, and script B defines a `foo` in the
 *current* scope.
 
-Again, that is **not** at all the *same effect*, not using `var` can have major 
+Again, that is **not** at all the *same effect*: not using `var` can have major 
 implications.
 
     // global scope
@@ -49,8 +49,8 @@ implications.
 
 Leaving out the `var` statement inside the function `test` will override the 
 value of `foo`. While this might not seem like a big deal at first, having 
-thousands of lines of JavaScript and not using `var` will introduce horrible and 
-hard to track down bugs.
+thousands of lines of JavaScript and not using `var` will introduce horrible,
+hard-to-track-down bugs.
 
     // global scope
     var items = [/* some list */];
@@ -116,7 +116,7 @@ JavaScript **hoists** declarations. This means that both `var` statements and
     }
 
 The above code gets transformed before any execution is started. JavaScript moves
-the `var` statements as well as the `function` declarations to the top of the 
+the `var` statements, as well as the `function` declarations to the top of the 
 nearest surrounding scope.
 
     // var statements got moved here
@@ -146,11 +146,11 @@ Missing block scoping will not only move `var` statements out of loops and
 their bodies, it will also make the results of certain `if` constructs 
 non-intuitive.
 
-In the original code the `if` statement seemed to modify the *global 
-variable* `goo`, while actually it modifies the *local variable* - after hoisting 
+In the original code, although the `if` statement seemed to modify the *global 
+variable* `goo`, it actually modifies the *local variable* - after hoisting 
 has been applied.
 
-Without the knowledge about *hoisting*, below code might seem to raise a 
+Without the knowledge about *hoisting*, the below code might seem to raise a 
 `ReferenceError`.
 
     // check whether SomeImportantThing has been initiliazed
@@ -173,18 +173,18 @@ moved to the top of the *global scope*.
 ### Name Resolution Order
 
 All scopes in JavaScript, including the *global scope*, have the special name 
-[`this`](#function.this) defined in them, which refers to the *current object*. 
+[`this`](#function.this), defined in them, which refers to the *current object*. 
 
-Function scopes also have the name [`arguments`](#function.arguments) defined in
-them which contains the arguments that were passed to a function.
+Function scopes also have the name [`arguments`](#function.arguments), defined in
+them, which contains the arguments that were passed to a function.
 
 For example, when trying to access a variable named `foo` inside the scope of a 
 function, JavaScript will lookup the name in the following order:
 
- 1. In case there is a `var foo` statement in the current scope use that.
- 2. If one of the function parameters is named `foo` use that.
- 3. If the function itself is called `foo` use that.
- 4. Go to the next outer scope and start with **#1** again.
+ 1. In case there is a `var foo` statement in the current scope, use that.
+ 2. If one of the function parameters is named `foo`, use that.
+ 3. If the function itself is called `foo`, use that.
+ 4. Go to the next outer scope, and start with **#1** again.
 
 > **Note:** Having a parameter called `arguments` will **prevent** the creation 
 > of the default `arguments` object.
@@ -223,7 +223,7 @@ while different in syntax, do behave the exact same way.
 ### In Conclusion
 
 It is recommended to always use an *anonymous wrapper* for encapsulating code in 
-its own namespace. This does not only protect code against name clashes, it 
+its own namespace. This does not only protect code against name clashes, but it 
 also allows for better modularization of programs.
 
 Additionally, the use of global variables is considered **bad practice**. **Any**