starting ambient docs

Author: basarat

SUMMARY.md

@@ -26,7 +26,10 @@
   * [Namespaces](docs/project/namespaces.md)
 * [TypeScript's Type System](docs/types/type-system.md)
   * [JS Migration Guide](docs/types/migrating.md)
-  * [Ambient Declarations](docs/types/ambient-declarations.md)
+  * [Ambient Declarations](docs/types/ambient/intro.md)
+    * [Declaration Files](docs/types/ambient/d.ts.md)
+    * [Variables](docs/types/ambient/variables.md)
+    * [Interfaces](docs/types/ambient/interfaces.md)
   * [`lib.d.ts`](docs/types/lib.d.ts.md)
   * [Functions](docs/types/type-compatability.md)
   * [Type Assertion](docs/types/type-assertion.md)

docs/types/ambient/d.ts.md

@@ -0,0 +1,17 @@
+### Declaration file
+You can tell TypeScript that you are trying to describe code that exists elsewhere (e.g. written in JavaScript/CoffeeScript/The runtime environment like the browser or nodejs) using the `declare` keyword. As a quick example: 
+
+```ts
+foo = 123; // Error: `foo` is not defined
+```
+vs.
+```ts
+declare var foo:any;
+foo = 123; // allowed 
+```
+
+You have the option of putting these declarations in a `.ts` file or in a `.d.ts` file. We highly recommend you in your real world projects you use a separate `.d.ts` (start with one called something like `globals.d.ts` or `vendor.d.ts`).
+
+If a file has the extension `.d.ts` then each root level definition much have the `declare` keyword prefixed to it to make it clear that the author knows that there will be *no code emitted by TypeScript to ensure that this defined item will exist at runtime*. 
+
+> For ambient declarations : Runtime JavaScript equivalent is a promise that you are making with the compiler. If these do not exist at runtime and you try to you them, things will break without warning.

docs/types/ambient/interfaces.md

@@ -0,0 +1,35 @@
+### Interfaces 
+Interfaces have *zero* runtime JS impact. There is a lot of power in TypeScript interfaces to declare the structure of variables. 
+
+The following two are equivalent declarations, the first uses an *inline annotation*, the second uses an *interface*: 
+
+```ts
+// Sample A
+declare var myPoint: { x: number; y: number; };
+
+// Sample B
+interface Point {
+    x: number; y: number;
+}
+declare var myPoint: Point;
+```
+
+However the beauty of *Sample B* is that if someone authors a library that builds on the `myPoint` library to add new members they can do that with if you used an interface: 
+
+```ts
+// Lib a.d.ts
+interface Point {
+    x: number; y: number;
+}
+declare var myPoint: Point;
+
+// Lib b.d.ts
+interface Point {
+    x: number; y: number; z: number;
+}
+
+// Your code 
+var myPoint.z; // Allowed!
+```
+
+This is because **interfaces in TypeScript are open ended**. This is a vital tenant of TypeScript that it allows you to mimic the extensibility of JavaScript using *interfaces*.

docs/types/ambient/intro.md

@@ -0,0 +1,10 @@
+## Ambient Declarations
+
+As we mentioned in [why TypeScript](../../why-typescript.md): 
+
+> A major design goal of TypeScript was to make it possible for you to safely and easily use existing JavaScript libraries in TypeScript. TypeScript does this by means of *declaration*
+
+Ambient declarations allow you to *safely use existing popular JavaScript libraries* and *incrementally migrate your JavaScript/CoffeeScript/Others-Compile-To-Js-Language project to TypeScript*.
+
+Studying patterns in ambient declarations for *third party JavaScript code* is good practice for annotating *your* TypeScript code base as well. This is why we present it so early on. 
+

docs/types/ambient/variables.md

@@ -0,0 +1,37 @@
+### Variables
+For example to tell TypeScript about the [`process` variable](https://nodejs.org/api/process.html) you *can* do:
+
+```ts
+declare var process:any;
+```
+
+> You don't *need* to do this for `process` as there is already a [community maintained `node.ts`](https://github.com/borisyankov/DefinitelyTyped/blob/master/node/node.d.ts)
+
+This allows you to use the `process` variable without TypeScript complaining: 
+
+```ts
+process.exit()
+```
+
+We recommend using an interface wherever possible e.g: 
+
+```ts
+interface Process {
+    exit(code?:number):void;
+}
+declare var process: Process;
+```
+
+This allows other people to *extend* the nature of these global variables while still telling TypeScript about such modifications. E.g. consider the following case where we add an `exitWithLogging` function to process for our amusement:
+
+```ts
+interface Process {
+    exitWithLogging(code?:number):void;
+}
+process.exitWithLogging = function() {
+    console.log("exiting");
+    process.exit.apply(process,arguments);
+}
+```
+
+Lets look at interfaces in a bit more detail next.

docs/types/migrating.md

@@ -73,4 +73,4 @@ declare var $: JQuery;
 
 This provides you an easier future update path.
 
-Again, a high quality `jquery.d.ts` exists at [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped). But you now know how to overcome any JavaScript -> TypeScript friction *quickly* when using third party JavaScript. We will look at ambient declarations in detail later.
+Again, a high quality `jquery.d.ts` exists at [DefinitelyTyped](https://github.com/borisyankov/DefinitelyTyped). But you now know how to overcome any JavaScript -> TypeScript friction *quickly* when using third party JavaScript. We will look at ambient declarations in detail next.