Merge pull request BonsaiDen#271 from chrisranderson/master

change 'that' to 'self', rename some 'foobar' examples

Author: timruffles

doc/en/array/general.md

@@ -40,13 +40,13 @@ While the *getter* of the `length` property simply returns the number of
 elements that are contained in the array, the *setter* can be used to 
 **truncate** the array.
 
-    var foo = [1, 2, 3, 4, 5, 6];
-    foo.length = 3;
-    foo; // [1, 2, 3]
+    var arr = [1, 2, 3, 4, 5, 6];
+    arr.length = 3;
+    arr; // [1, 2, 3]
 
-    foo.length = 6;
-    foo.push(4);
-    foo; // [1, 2, 3, undefined, undefined, undefined, 4]
+    arr.length = 6;
+    arr.push(4);
+    arr; // [1, 2, 3, undefined, undefined, undefined, 4]
 
 Assigning a smaller length truncates the array. Increasing it creates a sparse array.
 

doc/en/core/eval.md

@@ -2,27 +2,27 @@
 
 The `eval` function will execute a string of JavaScript code in the local scope.
 
-    var foo = 1;
+    var number = 1;
     function test() {
-        var foo = 2;
-        eval('foo = 3');
-        return foo;
+        var number = 2;
+        eval('number = 3');
+        return number;
     }
     test(); // 3
-    foo; // 1
+    number; // 1
 
 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;
+    var number = 1;
     function test() {
-        var foo = 2;
-        var bar = eval;
-        bar('foo = 3');
-        return foo;
+        var number = 2;
+        var copyOfEval = eval;
+        copyOfEval('number = 3');
+        return number;
     }
     test(); // 2
-    foo; // 3
+    number; // 3
 
 The use of `eval` should be avoided. 99.9% of its "uses" can be achieved
 **without** it.

doc/en/function/constructors.md

@@ -11,74 +11,74 @@ constructor.
 If the function that was called has no explicit `return` statement, then it
 implicitly returns the value of `this` - the new object. 
 
-    function Foo() {
-        this.bla = 1;
+    function Person(name) {
+        this.name = name;
     }
 
-    Foo.prototype.test = function() {
-        console.log(this.bla);
+    Person.prototype.logName = function() {
+        console.log(this.name);
     };
 
-    var test = new Foo();
+    var sean = new Person();
 
-The above calls `Foo` as constructor and sets the `prototype` of the newly
-created object to `Foo.prototype`.
+The above calls `Person` as constructor and sets the `prototype` of the newly
+created object to `Person.prototype`.
 
 In case of an explicit `return` statement, the function returns the value 
 specified by that statement, but **only** if the return value is an `Object`.
 
-    function Bar() {
-        return 2;
+    function Car() {
+        return 'ford';
     }
-    new Bar(); // a new object
+    new Car(); // a new object, not 'ford'
 
-    function Test() {
-        this.value = 2;
+    function Person() {
+        this.someValue = 2;
 
         return {
-            foo: 1
+            name: 'Charles'
         };
     }
-    new Test(); // the returned object
+    new Test(); // the returned object ({name:'Charles'}), not including someValue
 
 When the `new` keyword is omitted, the function will **not** return a new object. 
 
-    function Foo() {
-        this.bla = 1; // gets set on the global object
+    function Pirate() {
+        this.hasEyePatch = true; // gets set on the global object!
     }
-    Foo(); // undefined
+    var somePirate = Pirate(); // somePirate is undefined
 
-While the above example might still appear to work in some cases, due to the 
-workings of [`this`](#function.this) in JavaScript, it will use the 
+While the above example might still appear to work in some cases, due to the
+workings of [`this`](#function.this) in JavaScript, it will use the
 *global object* as the value of `this`.
 
 ### Factories
 
 In order to be able to omit the `new` keyword, the constructor function has to 
 explicitly return a value.
 
-    function Bar() {
-        var value = 1;
+    function Robot() {
+        var color = 'gray';
         return {
-            method: function() {
-                return value;
+            getColor: function() {
+                return color;
             }
         }
     }
-    Bar.prototype = {
-        foo: function() {}
+    Robot.prototype = {
+        someFunction: function() {}
     };
 
-    new Bar();
-    Bar();
+    new Robot();
+    Robot();
 
-Both calls to `Bar` return the same thing, a newly created object that
+Both calls to `Robot` return the same thing, a newly created object that
 has a property called `method`, which is a 
 [Closure](#function.closures).
 
-It should also be noted that the call `new Bar()` does **not** affect the
+It should also be noted that the call `new Robot()` does **not** affect the
 prototype of the returned object. While the prototype will be set on the newly
-created object, `Bar` never returns that new object.
+created object, `Robot` never returns that new object.
 
 In the above example, there is no functional difference between using and
 not using the `new` keyword.
@@ -92,19 +92,21 @@ lead to bugs.
 In order to create a new object, one should rather use a factory and construct a 
 new object inside of that factory.
 
-    function Foo() {
-        var obj = {};
-        obj.value = 'blub';
+    function CarFactory() {
+        var car = {};
+        car.owner = 'nobody';
 
-        var private = 2;
-        obj.someMethod = function(value) {
-            this.value = value;
+        var milesPerGallon = 2;
+
+        car.setOwner = function(newOwner) {
+            this.owner = newOwner;
         }
 
-        obj.getPrivate = function() {
-            return private;
+        car.getMPG = function() {
+            return milesPerGallon;
         }
-        return obj;
+
+        return car;
     }
 
 While the above is robust against a missing `new` keyword and certainly makes 

doc/en/function/this.md

@@ -68,18 +68,18 @@ mis-design of the language because it **never** has any practical use.
 A common misconception is that `this` inside of `test` refers to `Foo`; while in
 fact, it **does not**.
 
-In order to gain access to `Foo` from within `test`, it is necessary to create a 
+In order to gain access to `Foo` from within `test`, you can create a
 local variable inside of `method` that refers to `Foo`.
 
     Foo.method = function() {
-        var that = this;
+        var self = this;
         function test() {
-            // Use that instead of this here
+            // Use self instead of this here
         }
         test();
     }
 
-`that` is just a normal variable name, but it is commonly used for the reference to an 
+`self` is just a normal variable name, but it is commonly used for the reference to an
 outer `this`. In combination with [closures](#function.closures), it can also 
 be used to pass `this` values around.