Update README with latest changes. (#32)

* Update the README with more installation info.

- notes on use in add-ons
- clarify the normal installation process
- clarify the way that broccoli-typescript and IDEs interact

* Add notes to README (from mike-north) on what doesn't work.

Author: chriskrycho

README.md

@@ -1,39 +1,60 @@
 # ember-cli-typescript
 
-Enable typescript preprocessing on Ember 2.x apps.
+Use TypeScript in your Ember 2.x apps!
 
 
 ## Installation
 
-In addition to ember-cli-typescript, the following files are required:
+Just run:
+
+```
+ember install ember-cli-typescript
+```
+
+All dependencies will be added to your `package.json`, and you're ready to roll!
+
+In addition to ember-cli-typescript, the following files are installed:
 
 - [typescript](https://github.com/Microsoft/TypeScript) version 2.0.0 or greater
 - [@types/ember](https://www.npmjs.com/package/@types/ember)
 - [tsconfig](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)
 
-You can setup all of these at once with:
 
-```
-ember install ember-cli-typescript
-```
+## Write your add-ons in TypeScript
+
+To support shipping add-ons with TypeScript, move `ember-cli-typescript` from
+`devDependencies` to `dependencies` in your `package.json`.
+
+This is a function of the way Ember CLI add-ons work, not specific to TypeScript
+or this add-on. *Any* transpiler support (including this, CoffeeScript, or even
+Babel) needs to be specified in the `dependencies`, not `devDependencies`, to
+use it for developing the add-on itself: that's how its compiled output can be
+used in consuming apps or add-ons.
 
-All dependencies will be added to your package.json, and you're ready to roll!
 
 ## Configuration file notes
 
-If you make changes to the paths included in your `tsconfig.json`, you will need to restart the server to take the changes into account.
+If you make changes to the paths included in your `tsconfig.json`, you will need
+to restart the server to take the changes into account.
+
+### Quirks with `tsconfig.json`
 
-### Problem ###
+Additionally, depending on what you're doing, you may notice that your tweaks to
+`tsconfig.json` don't get picked up by the compiler at all.
 
-The configuration file is used by both Ember CLI/[broccoli](http://broccolijs.com/) and [VS Code](http://code.visualstudio.com/)/`tsc` command line compiler.
+#### The Problem
+
+The configuration file is used by both Ember CLI/[broccoli](http://broccolijs.com/)
+and `tsc` command line compiler (used by e.g. [VS Code](http://code.visualstudio.com/),
+JetBrains IDEs, etc.).
 
 Broccoli controls the inputs and the output folder of the various build steps
 that make the Ember build pipeline. Its expectation are impacted by Typescript
 configuration properties like "include", "exclude", "outFile", "outDir".
 
 We want to allow you to change unrelated properties in the tsconfig file.
 
-### Solution ###
+#### The Solution
 
 This addon takes the following approach to allow this dual use:
 
@@ -45,16 +66,17 @@ This addon takes the following approach to allow this dual use:
 
 - before calling broccoli the addon removes "outDir" and sets "noEmit" and "includes"
 
-### Customization ###
+### Customization
 
-You can customize this file further for your use case. For example to see the
-output of the compilation in a separate folder you are welcome to set and
-outDir and set noEmit to false. Then VS Code and tsc will generate files here
-while the broccoli pipeline will use its own temp folder.
+You can customize the `tsconfig.json` file further for your use case. For
+example to see the output of the compilation in a separate folder you are
+welcome to set and outDir and set noEmit to false. Then VS Code and tsc will
+generate files here while the broccoli pipeline will use its own temp folder.
 
-Please see the wiki for additional how to tips from other users or to add 
+Please see [the wiki] for additional how to tips from other users or to add 
 your own tips. If an use case is frequent enough we can codify in the plugin.
-https://github.com/emberwatch/ember-cli-typescript/wiki/tsconfig-how-to
+
+[the wiki]: https://github.com/emberwatch/ember-cli-typescript/wiki/tsconfig-how-to
 
 
 ## Incremental adoption
@@ -76,3 +98,60 @@ Create the file `.vscode/settings.json` with the following content:
     "typescript.tsdk" : "node_modules/typescript/lib"
 }
 ```
+
+## Not (yet) supported
+
+While TS works nicely for many things in Ember, there are a number of corners
+where it *won't* help you out. These are worth being aware of. Some of them are
+just a matter of further work on updating the [typings]; others are a matter of
+further support landing in TypeScript itself.
+
+[typings]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ember
+
+Here is the short list of things which do *not* work yet.
+
+### Extending from framework entities using `class` syntax
+
+```js
+export default MyComponent extends Ember.Component {
+}
+``` 
+
+### Type safety when invoking actions
+
+```ts
+actions: {
+   turnWheel(degrees: number) {
+      ...
+   }
+}
+``` 
+
+```hbs
+<!-- TypeScript compiler won't detect this type mismatch -->
+<button onclick={{action 'turnWheel' 'NOT-A-NUMBER'}}> Click Me </button>
+```
+
+```js
+// TypeScript compiler won't detect this type mismatch
+this.send('turnWheel', 'ALSO-NOT-A-NUMBER');
+```
+
+### Type safety when invoking KVO compliant accessors or mutators
+
+```ts
+Ember.Object.extend({
+  urls: <string[]> null,
+  port: 4200,
+  init() {
+     this._super(...arguments);
+     this.set('urls', []);
+  },
+  foo() {
+    // TypeScript won't detect these type mismatches
+    this.get('urls').addObject(51);
+    this.set('port', 3000);
+  }
+});
+``` 
+