The last couple of changes for today

Author: BonsaiDen

doc/casting.md

@@ -1,17 +1,12 @@
-## Type Casting
+## Type casting
 
-Since JavaScript is a weakly typed language one might think that it is the best
-to let the language to the type casting when comparing. But this is **not** a good
-idea, since the rules for converting between the types are extremely complex and
-even obscure at times.
-
-### Never use type coercion
-
-Do **never** compare by using the [double equal](#equality) - one little change
-in your code can break everything.
+JavaScript is a *weakly typed* language, so it will apply *type ceorcion*
+wherever possible.
 
     // These are true
-    new Number(10) == 10; // Number.toString() gets converted to a Number
+    new Number(10) == 10; // Number.toString() is converted
+                          // back to a number
+
     10 == '10';           // Strings gets converted to Number
     10 == '+10 ';         // More string madness
     10 == '010';          // And more 
@@ -22,9 +17,16 @@ in your code can break everything.
     10 == 010;
     10 == '-10'
 
-> **Note:** Number literals that start with a `0` are interpreted as octals
+> **Note:** Number literals that start with a `0` are interpreted as octal (Base
+> 8).
+
+In order to avoid that the use of the [strict equal operator](#equality) is
+recommended.
+
+But this does still not solve all the issues that arise from JavaScript's weak 
+typing system.
 
-### Madness with `new` and built in Types
+### Madness with `new` and built in types
 
 The constructors of the built in types like `Number` and `String` behave
 differently when being used with the `new` keyword and without it.
@@ -33,33 +35,29 @@ differently when being used with the `new` keyword and without it.
     Number(10) === 10;         // True, Number and Number
     new Number(10) + 0 === 10; // True, due to implicit conversion
 
-As you can see, using the built in type like `Number` as a constructor
-will create a new Number `Object`, but leaving out the `new` keyword will make
-it behave like a converter.
+Using the built in type like `Number` as a constructor will create a new number 
+`Object`, but leaving out the `new` keyword will make it behave like a converter.
 
-In addition, having literals or non `Object` values in there will activate more coercing
-magic.
+In addition, having literals or non `Object` values in there will activate more 
+coercing magic.
 
-Since the automatic casting done either by using different data types together, or the
-double equal operator is everything **but** consistent, the best option is to do
-the casting explicitly, basically all you can do is to cast to three different
-types.
+The best option is to do cast to one of the three possible types explicitly.
 
-### Casting to a String
+### Casting to a string
 
     '' + 10 === '10'; // true
 
-By using a empty string one can easily cast to a plain string.
+By using a empty string a value can easily be casted to a plain string.
 
-### Casting to a Number
+### Casting to a number
 
     +'10' === 10; // true
 
 Using the **unary** plus operator it is possible to cast to a plain number.
 
-### Casting to a Boolean
+### Casting to a boolean
 
-By using the **not** operator twice, one can convert anything to its boolean
+By using the **not** operator twice, a value can be converted to its boolean 
 value. 
 
     !!'foo';   // true

doc/equality.md

@@ -1,20 +1,14 @@
-## Equality and Comparisons
+## Equality and comparisons
 
 JavaScript has two different ways of comparing the values of objects for else
-equality. It has both the `==` (double equal) operator and the `===`
-(triple equal) operator.
+equality. 
 
-There is an important difference between those two and a good reason for 
-using **only** the triple equal version
+### The equals operator
 
-JavaScript has *weak typing* and therefore the creators of the language built in
-a way of doing *type coercion* when comparing two values. The only problem is
-that, instead of making *type coercion* optional, they made it the **default**.
+The equals operator consists of two equal signs: `==`
 
-So the `==` operator will try everything that the language specification allows for to
-convert the two values to the same type and then compare them.
-
-### The Double Equal Operator
+JavaScript features *weak typing*, that means, the equals operator does
+**coerce** types in order to compare them.
 
     ""           ==   "0"           // false
     0            ==   ""            // true
@@ -26,15 +20,20 @@ convert the two values to the same type and then compare them.
     null         ==   undefined     // true
     " \t\r\n"    ==   0             // true
 
-As you can see from this mess, there's absolutely **no** good reason to use the 
-`==` operator. All that *type coercion* does is to introduce hard to track 
-down errors due to implicit conversion of types.
+The above table shows the results of the type coercion and it is the main reason 
+why the use of `==` is regarded as bad practice, it introduces hard to track down
+bugs due to its complicated conversion rules.
+
+Additionally there is also a performance impact when type coercion is in play,
+since for example a string has to be converted to a number before the comparison
+is done. 
+
+### The strict equals operator
 
-There's also a performance impact when type coercion is in play. So `==` might
-end up being a lot slower, while `===` on the other hand, is always **at least**
-as fast, or faster when dealing with different types.
+The strict equals operator consists of **three** equal signs: `===`
 
-### The Triple Equal Operator
+Other than the normal equals operator, the strict equals operator does **not**
+coerce the types of its operands.
 
     ""           ===   "0"           // false
     0            ===   ""            // false
@@ -46,12 +45,16 @@ as fast, or faster when dealing with different types.
     null         ===   undefined     // false
     " \t\r\n"    ===   0             // false
 
-These are the results one coming from a strongly typed language would expect.
+The above results not only make a lot more sense, they also get rid of most of
+the weak typing in the language. This makes writing code a lot easier since
+things will break earlier and a lot of subtle bugs can be avoided.
 
-### Comparing Objects
+It will also be a lot faster when the operands are of different types.
 
-While both `==` and `===` are stated as equality operators, they behave different
-when used with at least one `Object`.
+### Comparing objects
+
+While both `==` and `===` are stated as **equality** operators, they behave 
+different when at least one of their operands happens to be an `Object`.
 
     {} === {};                   // false
     new String('foo') === 'foo'; // false
@@ -60,11 +63,12 @@ when used with at least one `Object`.
     foo === foo;                 // true
 
 Here both operators compare for **identity** and not equality - that is, they
-will compare for the same **instance** of the object, much like `is` in Python and a
-pointer comparison in C.
+will compare for the same **instance** of the object, much like `is` in Python 
+and a pointer comparison in C do.
+
+### Best practices
 
-### Best Practices
+It is highly recommended to **only** use the strict equals operator. In cases
+where types need to be coerced, it should be done [explicitly](#casting) and not
+left to the "magic" of the languages complicated coercing rules.
 
-**Always** use the `===` operator. There is never a **any** reason at all to 
-use `==`. You will avoid a lot of potential - yet again - subtle bugs this way. 
-In cases where you need to coerce types, do so **explicitly**.

doc/instanceof.md

@@ -1,9 +1,9 @@
 ## The `instanceof` operator
 
 `instanceof` is only useful when comparing custom made objects. Besides that it
-returns a mess similar to the [typeof operator](#the-typeof-operator).
+returns a mess similar to the [typeof operator](#typeof).
 
-### Comparing custom Objects
+### Comparing custom objects
 
     function Foo() {}
     function Bar() {}
@@ -20,12 +20,14 @@ returns a mess similar to the [typeof operator](#the-typeof-operator).
     'foo' instanceof String; // false
     'foo' instanceof Object; // false
 
-The important thing to note here is that `instanceof` will **of course** not work when the 
-two objects origin from different JavaScript contexts e.g. different documents in
+One important thing to note is that `instanceof` does of course not work on
+objects that origin from different JavaScript contexts. For example: Different
+documents in a web browser.
 a Web Browser.
 
-### Best Practices
+### Best practices
+
+The `instanceof` operator should only be used when dealing with custom made 
+objects that origin from the same JavaScript context. Just like the `typeof` 
+operator, every other use of it should be **avoided**.
 
-Only use `instanceof` when dealing with custom made objects, **never** use it like
-the `typeof` operator - it will behave just as badly and even worse when dealing
-with objects from different contexts.

doc/objects.md

@@ -37,6 +37,25 @@ object [inherits](#prototype) from `Object.prototype` and has no
     // a new object with a property called 'test' with value 12
     var bar = {test: 12}; 
 
+### Access of properties
+
+The properties of an object can be accessed in two ways. Either via the dot
+notation, or the square bracket notation.
+    
+    var foo = {name: 'Kitten'}
+    foo.name; // kitten
+    foo['name']; // kitten
+    
+    var get = 'name';
+    foo[get]; // kitten
+    
+    foo.1234; // SyntaxError
+    foo['1234']; // works
+
+Both notation are identical in their workings, the only difference being that
+the square bracket notation allows for dynamic setting of properties as well as
+the use of property names that would otherwise lead to a syntax error.
+
 ### Notation of keys
 
     var test = {
@@ -50,5 +69,5 @@ another mis-design in JavaScript's parser, the above raises a `SyntaxError`.
 The error is getting raised because `delete` is a *keyword* of the language, 
 therefore it must be, just like `case`, notated as a string literal.
 
- [1]: http://en.wikipedia.org/wiki/Hashmap
+[1]: http://en.wikipedia.org/wiki/Hashmap
 

doc/semicolon.md

@@ -1,15 +1,17 @@
-## Automatic Semicolon Insertion
+## Automatic semicolon insertion
 
-Although JavaScript has C style syntax, it does not enforce the use of
-semicolons in the source code, but since the parser still needs them in order to
-be able to figure out what the code should do, it inserts them automatically.
+Although JavaScript has C style syntax, it does **not** enforce the use of
+semicolons in the source code. Since the parser still needs semicolons in order 
+to be able to figure out what the code should do, it inserts them 
+**automatically**.
 
-When the parser encounters an error due to new line that is not preceded by a 
+When the parser encounters an error due to newline that is not preceded by a 
 semicolon, it will insert a semicolon automatically and try again. When the
 parser still hits an error, it will raise it, otherwise it will simply proceed.
 
-This is one of the **biggest** flaws in the language since it makes the below
-code work with a completely different result than intended.
+The automatic insertion of semicolon is considered to be one of **biggest**
+design flaws in the language. It makes the below code work, but  with a 
+completely different result than intended.
 
     return
     {
@@ -19,16 +21,16 @@ code work with a completely different result than intended.
 After the JavaScript parser fixed it, this will **not** return an object which 
 has a property called `foo`, it will instead simply return `undefined`.
 
-### How the Parser "fixes" missing Semicolons
+### How the parser "fixes" missing semicolons
 
-    return // parse error, expected a semicolon. Automatic insertion happens
-    { // Although there's no block scope in JS, block syntax is handle fined
+    return // Error, semicolon expected. Automatic insertion happens
+    { // Block syntax is handle just fine
 
-        // foo is not interpreted as an object key, but as a label
+        // foo is not interpreted as property name, but as a label
         foo: 1 // JavaScript supports single expression evaluation
                // So 1 evaluates to 1 and no error is being raised
 
-    } // Another semicolon gets inserted here
+    } // Automatic semicolon insertioN
 
 After the parser has done its "magic", the resulting code has completely
 different behavior.
@@ -40,9 +42,9 @@ different behavior.
         foo: 1
     };
 
-### Best Practices
+### Best practices
 
-**Never** omit semicolons. Also, always keep your `{}` on the **same** line to 
-avoid such subtle mistakes. It's also good style to **never** make use the 
-possibility of omitting the curly braces for one line `if / else` statements.
+It is **highly** recommended to **never** omit semicolons, it is further
+recommended to keep braces on the same line with their associated statements and
+never omit them for one line `if` / `else` statements.
 

doc/undefined.md

@@ -35,8 +35,8 @@ anonymous function wrapper and add an additional parameter which one passed
 
     var undefined = 123;
     (function(something, foo, undefined) {
-        // undefined in the local scope does now again refer to the value
-        // undefined
+        // undefined in the local scope does 
+        // now again refer to the value
 
     })('Hello World', 42);