docs: update from GitBook -- 37 pages modified

Author: chriskrycho

docs/SUMMARY.md

@@ -0,0 +1,39 @@
+# Table of contents
+
+* [Initial page](../index.md)
+* [Getting Started](getting-started/README.md)
+  * [Installation](getting-started/installation.md)
+  * [Configuration](getting-started/configuration.md)
+* [Working With Ember Classic](legacy/README.md)
+  * [EmberComponent](legacy/ember-component.md)
+  * [Mixins](legacy/mixins.md)
+  * [Computed Properties](legacy/computed-properties.md)
+  * [EmberObject](legacy/ember-object.md)
+  * [Legacy Ember Guide](legacy/overview.md)
+* [Working With Ember Data](ember-data/README.md)
+  * [Overview: Ember Data](ember-data/overview.md)
+  * [Models](ember-data/models.md)
+* [cookbook](cookbook/README.md)
+  * [Overview](cookbook/overview.md)
+  * [Working with route models](cookbook/working-with-route-models.md)
+* [type-defs](type-defs/README.md)
+  * [Understanding the Package Names](type-defs/package-names.md)
+* [Overview](index.md)
+* [ts](ts/README.md)
+  * [Building Addons in TypeScript](ts/with-addons.md)
+  * [TypeScript and Ember](ts/overview.md)
+  * [Decorators](ts/decorators.md)
+  * [Using TypeScript with Ember effectively](ts/using-ts-effectively.md)
+  * [Current limitations](ts/current-limitations.md)
+* [Upgrading from 1.x](upgrade-notes.md)
+* [Working With Ember](ember/README.md)
+  * [Controllers](ember/controllers.md)
+  * [Services](ember/services.md)
+  * [Overview: Ember](ember/overview.md)
+  * [Testing](ember/testing.md)
+  * [Components](ember/components.md)
+  * [Helpers](ember/helpers.md)
+  * [Routes](ember/routes.md)
+* [troubleshooting](troubleshooting/README.md)
+  * [Conflicting Type Dependencies](troubleshooting/conflicting-types.md)
+

docs/cookbook/README.md

@@ -0,0 +1,2 @@
+# cookbook
+

docs/cookbook/overview.md

@@ -3,11 +3,8 @@
 This “cookbook” section contains recipes for various scenarios you may encounter while working on your app or addon.
 
 {% hint style="info" %}
-
-Have an idea for an item that should fit here? [Open an issue for it!][gh-issue] We'd love to help you help us make this experience more awesome for everyone.
-
-[gh-issue]: https://github.com/typed-ember/ember-cli-typescript/issues/new/choose
-
+Have an idea for an item that should fit here? [Open an issue for it!](https://github.com/typed-ember/ember-cli-typescript/issues/new/choose) We'd love to help you help us make this experience more awesome for everyone.
 {% endhint %}
 
-- <LinkTo @route='docs.cookbook.working-with-route-models'>Working with route models</LinkTo>
+* Working with route models
+

docs/cookbook/working-with-route-models.md

@@ -4,7 +4,7 @@ We often use routes’ models throughout our application, since they’re a core
 
 We can start by defining some type utilities to let us get the resolved value returned by a route’s model hook:
 
-```ts
+```typescript
 import Route from '@ember/routing/route';
 
 /**
@@ -21,21 +21,21 @@ export type ModelFrom<R extends Route> = Resolved<ReturnType<R['model']>>;
 
 How that works:
 
-- `Resolved<P>` says "if this is a promise, the type here is whatever the promise resolves to; otherwise, it's just the value"
-- `ReturnType<T>` gets the return value of a given function
-- `R['model']` (where `R` has to be `Route` itself or a subclass) uses TS's mapped types to say "the property named `model` on `R`
+* `Resolved<P>` says "if this is a promise, the type here is whatever the promise resolves to; otherwise, it's just the value"
+* `ReturnType<T>` gets the return value of a given function
+* `R['model']` \(where `R` has to be `Route` itself or a subclass\) uses TS's mapped types to say "the property named `model` on `R`
 
-Putting those all together,  `ModelFrom<Route>` ends up giving you the resolved value returned from the `model` hook for a given route:
+Putting those all together, `ModelFrom<Route>` ends up giving you the resolved value returned from the `model` hook for a given route:
 
-```ts
+```typescript
 type MyRouteModel = ModelFrom<MyRoute>;
 ```
 
 ## `model` on the controller
 
 We can use this functionality to guarantee that the `model` on a `Controller` is always exactly the type returned by `Route::model` by writing something like this:
 
-```ts
+```typescript
 import Controller from '@ember/controller';
 import MyRoute from '../routes/my-route';
 import { ModelFrom } from '../lib/type-utils';
@@ -45,6 +45,7 @@ export default class ControllerWithModel extends Controller {
 }
 ```
 
-Now, our controller’s `model` property will *always* stay in sync with the corresponding route’s model hook.
+Now, our controller’s `model` property will _always_ stay in sync with the corresponding route’s model hook.
+
+**Note:** this _only_ works if you do not mutate the `model` in either the `afterModel` or `setupController` hooks on the route! That's generally considered to be a bad practice anyway. If you do change the type there, you'll need to define the type in some other way and make sure your route's model is defined another way.
 
-**Note:** this *only* works if you do not mutate the `model` in either the `afterModel` or `setupController` hooks on the route! That's generally considered to be a bad practice anyway. If you do change the type there, you'll need to define the type in some other way and make sure your route's model is defined another way.

docs/ember-data/README.md

@@ -0,0 +1,2 @@
+# Working With Ember Data
+

docs/ember-data/models.md

@@ -2,25 +2,23 @@
 
 Ember Data models are normal TypeScript classes, but with properties decorated to define how the model represents an API resource and relationships to other resources. The decorators the library supplies "just work" with TypeScript at runtime, but require type annotations to be useful with TypeScript.
 
-For an overview of using Ember's decorators with TypeScript, see <LinkTo @route='docs.ts.decorators'>our overview</LinkTo>.
+For an overview of using Ember's decorators with TypeScript, see our overview.
 
 ## `@attr`
 
 The type returned by the `@attr` decorator is whatever [Transform](https://api.emberjs.com/ember-data/release/classes/Transform) is applied via the invocation.
 
-- If you supply no argument to `@attr`, the value is passed through without transformation.
-
-- If you supply one of the built-in transforms, you will get back a corresponding type:
-    - `@attr('string')` → `string`
-    - `@attr(number)` → `number`, 
-    - `@attr('boolean')` → `boolean`
-    - `@attr'date')` → `Date`
-
-- If you supply a custom transform, you will get back the type returned by your transform.
+* If you supply no argument to `@attr`, the value is passed through without transformation.
+* If you supply one of the built-in transforms, you will get back a corresponding type:
+  * `@attr('string')` → `string`
+  * `@attr(number)` → `number`, 
+  * `@attr('boolean')` → `boolean`
+  * `@attr'date')` → `Date`
+* If you supply a custom transform, you will get back the type returned by your transform.
 
 So, for example, you might write a class like this:
 
-```ts
+```typescript
 import Model, { attr } from '@ember-data/object';
 import CustomType from '../transforms/custom-transform';
 
@@ -39,13 +37,13 @@ export default class User extends Model {
 }
 ```
 
-**Very important:** Even more than with decorators in general, you should be careful when deciding whether to mark a property as optional `?` or definitely present (no annotation): Ember Data will default to leaving a property empty if it is not supplied by the API or by a developer when creating it. That is: the *default* for Ember corresponds to an optional field on the model.
+**Very important:** Even more than with decorators in general, you should be careful when deciding whether to mark a property as optional `?` or definitely present \(no annotation\): Ember Data will default to leaving a property empty if it is not supplied by the API or by a developer when creating it. That is: the _default_ for Ember corresponds to an optional field on the model.
 
-The *safest* type you can write for an Ember Data model, therefore, leaves every property optional: this is how models *actually* behave. If you choose to mark properties as definitely present by leaving off the `?`, you should take care to guarantee that this is a guarantee your API upholds, and that ever time you create a record from within the app, *you* uphold those guarantees.
+The _safest_ type you can write for an Ember Data model, therefore, leaves every property optional: this is how models _actually_ behave. If you choose to mark properties as definitely present by leaving off the `?`, you should take care to guarantee that this is a guarantee your API upholds, and that ever time you create a record from within the app, _you_ uphold those guarantees.
 
 One way to make this safer is to supply a default value using the `defaultValue` on the options hash for the attribute:
 
-```ts
+```typescript
 import Model, { attr } from '@ember-data/object';
 
 export default class User extends Model {
@@ -62,15 +60,14 @@ export default class User extends Model {
 
 ## `@belongsTo`
 
-The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` (which it is by default).
-
-- If the value is `true`, the type you should use is `DS.PromiseObject<Model>`, where `Model` is the type of the model you are creating a relationship to.
+The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` \(which it is by default\).
 
-- If the value is `false`, the type is `Model`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `true`, the type you should use is `DS.PromiseObject<Model>`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `false`, the type is `Model`, where `Model` is the type of the model you are creating a relationship to.
 
 So, for example, you might define a class like this:
 
-```ts
+```typescript
 import Model, { belongsTo } from '@ember-data/model';
 import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
 import User from './user';
@@ -85,24 +82,23 @@ export default class Post extends Model {
 }
 ```
 
-These are *type*-safe to define as always present, that is to leave off the `?` optional marker:
+These are _type_-safe to define as always present, that is to leave off the `?` optional marker:
 
-- accessing an async relationship will always return a `PromiseObject`, which itself may or may not ultimately resolve to a value—depending on the API response—but will always be present itself.
-- accessing a non-async relationship which is known to be associated but has not been loaded will trigger an error, so all access to the property will be safe *if* it resolves at all.
+* accessing an async relationship will always return a `PromiseObject`, which itself may or may not ultimately resolve to a value—depending on the API response—but will always be present itself.
+* accessing a non-async relationship which is known to be associated but has not been loaded will trigger an error, so all access to the property will be safe _if_ it resolves at all.
 
-Note, however, that this type-safety is not a guarantee of there being no runtime error: you still need to uphold the contract for non-async relationships (that is: loading the data first, or side-loading it with the request) to avoid throwing an error!
+Note, however, that this type-safety is not a guarantee of there being no runtime error: you still need to uphold the contract for non-async relationships \(that is: loading the data first, or side-loading it with the request\) to avoid throwing an error!
 
 ## `@hasMany`
 
-The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` (which it is by default).
+The type returned by the `@hasMany` decorator depends on whether the relationship is `{ async: true }` \(which it is by default\).
 
-- If the value is `true`, the type you should use is `DS.PromiseManyArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
-
-- If the value is `false`, the type is `EmberArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `true`, the type you should use is `DS.PromiseManyArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
+* If the value is `false`, the type is `EmberArray<Model>`, where `Model` is the type of the model you are creating a relationship to.
 
 So, for example, you might define a class like this:
 
-```ts
+```typescript
 import Model, { hasMany } from '@ember-data/model';
 import EmberArray from '@ember/array';
 import DS from 'ember-data'; // NOTE: this is a workaround, see discussion below!
@@ -118,10 +114,11 @@ export default class Thread extends Model {
 }
 ```
 
-The same basic rules about the safety of these lookups as with `@belongsTo` apply to these types. The difference is just that in `@hasMany` the resulting types are *arrays* rather than single objects.
+The same basic rules about the safety of these lookups as with `@belongsTo` apply to these types. The difference is just that in `@hasMany` the resulting types are _arrays_ rather than single objects.
 
 ## Importing `PromiseObject` and `PromiseManyArray`
 
-There is no public import path in the [Ember Data Packages](https://emberjs.github.io/rfcs/0395-ember-data-packages.html) API for the `PromiseObject` and `PromiseManyArray` types. These types are slowly being disentangled from Ember Data and will eventually be removed. However, until they are, we need a way to refer to them. For *now*, the best option is to refer to them via the legacy `DS` import.
+There is no public import path in the [Ember Data Packages](https://emberjs.github.io/rfcs/0395-ember-data-packages.html) API for the `PromiseObject` and `PromiseManyArray` types. These types are slowly being disentangled from Ember Data and will eventually be removed. However, until they are, we need a way to refer to them. For _now_, the best option is to refer to them via the legacy `DS` import.
 
 In the future, they will become unnecesary, as the types will simply be `Promise<Model>` and `Promise<Array<Model>>`.
+

docs/ember-data/overview.md

@@ -1,5 +1,6 @@
 # Overview: Ember Data
 
-In this section, we cover how to use TypeScript effectively with specific Ember Data APIs (anything you'd find under the `@ember-data` package namespace).
+In this section, we cover how to use TypeScript effectively with specific Ember Data APIs \(anything you'd find under the `@ember-data` package namespace\).
+
+We do _not_ cover general usage of Ember Data; instead, we assume that as background knowledge. Please see the Ember Data [Guides](https://guides.emberjs.com/release/models) and [API docs](https://api.emberjs.com/ember-data/release)!
 
-We do *not* cover general usage of Ember Data; instead, we assume that as background knowledge. Please see the Ember Data [Guides](https://guides.emberjs.com/release/models) and [API docs](https://api.emberjs.com/ember-data/release)!

docs/ember/README.md

@@ -0,0 +1,2 @@
+# Working With Ember
+