Merge branch 'master' into updateReactWebpack

Author: mhegazy

pages/Basic Types.md

@@ -214,7 +214,7 @@ Once again, more on union types later on.
 # Never
 
 The `never` type represents the type of values that never occur.
-For instance, `never` is the return type for a function expression or an arrow function expresssion that always throws an exception or one that never returns;
+For instance, `never` is the return type for a function expression or an arrow function expression that always throws an exception or one that never returns;
 Variables also acquire the type `never` when narrowed by any type guards that can never be true.
 
 The `never` type is a subtype of, and assignable to, every type; however, *no* type is a subtype of, or assignable to, `never` (except `never` itself).

pages/Classes.md

@@ -1,6 +1,6 @@
 # Introduction
 
-Traditional JavaScript focuses on functions and prototype-based inheritance as the basic means of building up reusable components, but this may feel a bit awkward to programmers more comfortable with an object-oriented approach, where classes inherit functionality and objects are built from these classes.
+Traditional JavaScript uses functions and prototype-based inheritance to build up reusable components, but this may feel a bit awkward to programmers more comfortable with an object-oriented approach, where classes inherit functionality and objects are built from these classes.
 Starting with ECMAScript 2015, also known as ECMAScript 6, JavaScript programmers will be able to build their applications using this object-oriented class-based approach.
 In TypeScript, we allow developers to use these techniques now, and compile them down to JavaScript that works across all major browsers and platforms, without having to wait for the next version of JavaScript.
 

pages/Compiler Options.md

@@ -453,6 +453,7 @@ function validate<T>(target: any, propertyKey: string, descriptor: TypedProperty
         if (!(value instanceof type)) {
             throw new TypeError("Invalid type.");
         }
+        set(value);
     }
 }
 ```

pages/Decorators.md

@@ -40,13 +40,13 @@ You should use relative imports for your own modules that are guaranteed to main
 
 A non-relative import can be resolved relative to `baseUrl`, or through path mapping, which we'll cover below.
 They can also resolve to [ambient module declarations](./Modules.md#ambient-modules).
-Use non-relative paths when importing any of your external dependnecies.
+Use non-relative paths when importing any of your external dependencies.
 
 ## Module Resolution Strategies
 
 There are two possible module resolution strategies: [Node](#node) and [Classic](#classic).
 You can use the `--moduleResolution` flag to specify the module resolution strategy.
-The default if not specified is [Node](#node).
+If not specified, the default is [Classic](#classic) for `--module AMD | System | ES2015` or [Node](#node) otherwise.
 
 ### Classic
 
@@ -213,13 +213,15 @@ Here is an example for how to specify the `"paths"` property for `jquery`.
 ```json
 {
   "compilerOptions": {
+    "baseUrl": ".", // This must be specified if "paths" is.
     "paths": {
-      "jquery": ["node_modules/jquery/dist/jquery.d.ts"]
+      "jquery": ["node_modules/jquery/dist/jquery"]
     }
+  }
 }
 ```
 
-Using `"paths"` also allow for more sophisticated mappings including multiple fall back locations.
+Using `"paths"` also allows for more sophisticated mappings including multiple fall back locations.
 Consider a project configuration where only some modules are available in one location, and the rest are in another.
 A build step would put them all together in one place.
 The project layout may look like:
@@ -240,15 +242,15 @@ The corresponding `tsconfig.json` would look like:
 
 ```json
 {
-    "compilerOptions": {
-        "baseUrl": ".",
-        "paths": {
-            "*": [
-                    "*",
-                    "generated/*"
-                ]
-            }
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "*": [
+        "*",
+        "generated/*"
+      ]
     }
+  }
 }
 ```
 

pages/Module Resolution.md

@@ -114,4 +114,5 @@ Here's a revised example:
 ## Trade-offs of Modules
 
 Just as there is a one-to-one correspondence between JS files and modules, TypeScript has a one-to-one correspondence between module source files and their emitted JS files.
-One effect of this is that it's not possible to use the `--outFile` compiler switch to concatenate multiple module source files into a single JavaScript file.
+One effect of this is that it's not possible to concatenate multiple module source files depending on the module system you target.
+For instance, you can't use the `outFile` option while targeting `commonjs` or `umd`, but with TypeScript 1.8 and later, [it's possible](https://www.typescriptlang.org/docs/release-notes/typescript-1.8.html#concatenate-amd-and-system-modules-with---outfile) to use `outFile` when targeting `amd` or `system`.

pages/Namespaces and Modules.md

@@ -475,7 +475,7 @@ function f([first, second]: [number, number]) {
 f(input);
 ```
 
-You can create a variable for the remaining items in a list using the syntax `...name`:
+You can create a variable for the remaining items in a list using the syntax `...`:
 
 ```ts
 let [first, ...rest] = [1, 2, 3, 4];
@@ -506,7 +506,7 @@ let o = {
     b: 12,
     c: "bar"
 }
-let {a, b} = o;
+let { a, b } = o;
 ```
 
 This creates new variables `a` and `b` from `o.a` and `o.b`.
@@ -515,18 +515,26 @@ Notice that you can skip `c` if you don't need it.
 Like array destructuring, you can have assignment without declaration:
 
 ```ts
-({a, b} = {a: "baz", b: 101});
+({ a, b } = { a: "baz", b: 101 });
 ```
 
 Notice that we had to surround this statement with parentheses.
 JavaScript normally parses a `{` as the start of block.
 
+You can create a variable for the remaining items in an object using the syntax `...`:
+
+```ts
+let { a, ...passthrough } = o;
+let total = passthrough.b + passthrough.c.length;
+
+```
+
 ### Property renaming
 
 You can also give different names to properties:
 
 ```ts
-let {a: newName1, b: newName2} = o;
+let { a: newName1, b: newName2 } = o;
 ```
 
 Here the syntax starts to get confusing.
@@ -542,16 +550,16 @@ Confusingly, the colon here does *not* indicate the type.
 The type, if you specify it, still needs to be written after the entire destructuring:
 
 ```ts
-let {a, b}: {a: string, b: number} = o;
+let { a, b }: { a: string, b: number } = o;
 ```
 
 ### Default values
 
 Default values let you specify a default value in case a property is undefined:
 
 ```ts
-function keepWholeObject(wholeObject: {a: string, b?: number}) {
-    let {a, b = 1001} = wholeObject;
+function keepWholeObject(wholeObject: { a: string, b?: number }) {
+    let { a, b = 1001 } = wholeObject;
 }
 ```
 
@@ -563,8 +571,8 @@ Destructuring also works in function declarations.
 For simple cases this is straightforward:
 
 ```ts
-type C = {a: string, b?: number}
-function f({a, b}: C): void {
+type C = { a: string, b?: number }
+function f({ a, b }: C): void {
     // ...
 }
 ```
@@ -573,26 +581,81 @@ But specifying defaults is more common for parameters, and getting defaults righ
 First of all, you need to remember to put the type before the default value.
 
 ```ts
-function f({a, b} = {a: "", b: 0}): void {
+function f({ a, b } = { a: "", b: 0 }): void {
     // ...
 }
-f(); // ok, default to {a: "", b: 0}
+f(); // ok, default to { a: "", b: 0 }
 ```
 
 Then, you need to remember to give a default for optional properties on the destructured property instead of the main initializer.
 Remember that `C` was defined with `b` optional:
 
 ```ts
-function f({a, b = 0} = {a: ""}): void {
+function f({ a, b = 0 } = { a: "" }): void {
     // ...
 }
-f({a: "yes"}) // ok, default b = 0
-f() // ok, default to {a: ""}, which then defaults b = 0
+f({ a: "yes" }) // ok, default b = 0
+f() // ok, default to { a: "" }, which then defaults b = 0
 f({}) // error, 'a' is required if you supply an argument
 ```
 
 Use destructuring with care.
-As the previous example demonstrates, anything but the simplest destructuring expressions have a lot of corner cases.
+As the previous example demonstrates, anything but the simplest destructuring expression is confusing.
 This is especially true with deeply nested destructuring, which gets *really* hard to understand even without piling on renaming, default values, and type annotations.
 Try to keep destructuring expressions small and simple.
 You can always write the assignments that destructuring would generate yourself.
+
+## Spread
+
+The spread operator is the opposite of destructuring.
+It allows you to spread an array into another array, or an object into another object.
+For example:
+
+```ts
+let first = [1, 2];
+let second = [3, 4];
+let bothPlus = [0, ...first, ...second, 5];
+```
+
+This gives bothPlus the value `[0, 1, 2, 3, 4, 5]`.
+Spreading creates a shallow copy of `first` and `second`.
+They are not changed by the spread.
+
+You can also spread objects:
+
+```ts
+let defaults = { food: "spicy", price: "$$", ambiance: "noisy" };
+let search = { ...defaults, food: "rich" };
+```
+
+Now `search` is `{ food: "rich", price: "$$", ambiance: "noisy" }`.
+Object spreading is more complex than array spreading.
+Like array spreading, it proceeds from left-to-right, but the result is still an object.
+This means that properties that come later in the spread object overwrite properties that come earlier.
+So if we modify the previous example to spread at the end:
+
+```ts
+let defaults = { food: "spicy", price: "$$", ambiance: "noisy" };
+let search = { food: "rich", ...defaults };
+```
+
+Then the `food` property in `defaults` overwrites `food: "rich"`, which is not what we want in this case.
+
+Object spread also has a couple of other surprising limits.
+First, it only includes own, enumerable properties.
+Basically, that means you lose methods when you spread instances of an object:
+
+```ts
+class C {
+  p = 12;
+  m() {
+  }
+}
+let c = new C();
+let clone = { ...c };
+clone.p; // ok
+clone.m(); // error!
+```
+
+Second, the Typescript compiler doesn't allow spreads of type parameters from generic functions.
+That feature is expected in future versions of the language.

pages/Variable Declarations.md

@@ -114,9 +114,10 @@ declare function getWidget(s: string): Widget[];
 
 > When specifying a greeting, you must pass a `GreetingSettings` object.
 > This object has the following properties:
-> - greeting: Mandatory string
-> - duration: Optional length of time (in milliseconds)
-> - color: Optional string, e.g. '#ff00ff'
+>
+> 1- greeting: Mandatory string
+> 2- duration: Optional length of time (in milliseconds)
+> 3- color: Optional string, e.g. '#ff00ff'
 
 *Code*
 

pages/declaration files/By Example.md

@@ -143,19 +143,19 @@ When an earlier overload is "more general" than a later one, the later one is ef
 
 ```ts
 /* WRONG */
-interface Moment {
-    diff(b: MomentComparable): number;
-    diff(b: MomentComparable, unitOfTime: string): number;
-    diff(b: MomentComparable, unitOfTime: string, round: boolean): number;
+interface Example {
+    diff(one: string): number;
+    diff(one: string, two: string): number;
+    diff(one: string, two: string, three: boolean): number;
 }
 ```
 
 *Do* use optional parameters whenever possible:
 
 ```ts
 /* OK */
-interface Moment {
-    diff(b: MomentComparable, unitOfTime?: string, round?: boolean): number;
+interface Example {
+    diff(one: string, two?: string, three?: boolean): number;
 }
 ```
 
@@ -169,7 +169,7 @@ This code, for example, exposes a bug only when the signature is correctly writt
 
 ```ts
 function fn(x: (a: string, b: number, c: number) => void) { }
-var x: Moment;
+var x: Example;
 // When written with overloads, OK -- used first overload
 // When written with optionals, correctly an error
 fn(x.diff);
@@ -180,10 +180,10 @@ Because unspecified parameters appear as `undefined` in JavaScript, it's usually
 This code, for example, should be OK under strict nulls:
 
 ```ts
-var x: Moment;
+var x: Example;
 // When written with overloads, incorrectly an error because of passing 'undefined' to 'string'
 // When written with optionals, correctly OK
-x.diff(something, someOtherThing ? undefined : "hour");
+x.diff("something", true ? undefined : "hour");
 ```
 
 ## Use Union Types

pages/declaration files/Do's and Don'ts.md

@@ -0,0 +1,21 @@
+# Performance Improvements
+
+The 1.1 compiler is typically around 4x faster than any previous release. See [this blog post for some impressive charts.](http://blogs.msdn.com/b/typescript/archive/2014/10/06/announcing-typescript-1-1-ctp.aspx)
+
+# Better Module Visibility Rules
+
+TypeScript now only strictly enforces the visibility of types in modules if the `--declaration` flag is provided. This is very useful for Angular scenarios, for example:
+
+```ts
+module MyControllers {
+  interface ZooScope extends ng.IScope {
+    animals: Animal[];
+  }
+  export class ZooController {
+    // Used to be an error (cannot expose ZooScope), but now is only
+    // an error when trying to generate .d.ts files
+    constructor(public $scope: ZooScope) { }
+    /* more code */
+  }
+}
+```