docs(dialog): document MdDialog (#1569)

Author: feloy

README.md

@@ -61,7 +61,7 @@ High level items planned for October 2016:
 | menu             | Initial version, needs enhancements | [README][17] |   [#119][0119] |
 | tooltip          | Initial version, needs enhancements | [README][18] |              - |
 | ripples          |  Available, but needs to be applied | [README][19] |   [#108][0108] |
-| dialog           |  Started, not yet ready for release |           -  |   [#114][0114] |
+| dialog           |  Started, not yet ready for release | [README][22] |   [#114][0114] |
 | snackbar / toast | Initial version, needs enhancements | [README][21] |   [#115][0115] |
 | select           |                      Design started |           -  |   [#118][0118] |
 | textarea         |                         Not started |           -  |   [#546][0546] |
@@ -102,6 +102,7 @@ High level items planned for October 2016:
 [19]: https://github.com/angular/material2/blob/master/src/lib/core/ripple/README.md
 [20]: https://github.com/angular/material2/blob/master/docs/theming.md
 [21]: https://github.com/angular/material2/blob/master/src/lib/snack-bar/README.md
+[22]: https://github.com/angular/material2/blob/master/src/lib/dialog/README.md
 
 [0107]: https://github.com/angular/material2/issues/107
 [0119]: https://github.com/angular/material2/issues/119

src/lib/dialog/README.md

@@ -0,0 +1,88 @@
+# MdDialog
+
+MdDialog is a service, which opens dialogs components in the view. 
+
+### Methods
+
+| Name |  Description |
+| --- | --- |
+| `open(component: ComponentType<T>, config: MdDialogConfig): MdDialogRef<T>` | Creates and opens a dialog matching material spec. |
+
+### Config
+
+| Key |  Description |
+| --- | --- |
+| `viewContainerRef: ViewContainerRef` | The view container ref to attach the dialog to. |
+| `role: DialogRole = 'dialog'` | The ARIA role of the dialog element. Possible values are `dialog` and `alertdialog`. Defaults to `dialog`. |
+
+## MdDialogRef
+
+A reference to the dialog created by the MdDialog `open` method.
+
+### Methods
+
+| Name |  Description |
+| --- | --- |
+| `close(dialogResult?: any)` | Closes the dialog, pushing a value to the afterClosed observable. |
+| `afterClosed(): Observable<any>` | Returns an observable which will emit the dialog result, passed to the `close` method above. |
+
+## Example
+The service can be injected in a component.
+
+```ts
+@Component({
+  selector: 'pizza-component',
+  template: `
+  <button type="button" (click)="openDialog()">Open dialog</button>
+  `
+})
+export class PizzaComponent {
+
+  dialogRef: MdDialogRef<PizzaDialog>;
+
+  constructor(
+    public dialog: MdDialog,
+    public viewContainerRef: ViewContainerRef) { }
+
+  openDialog() {
+    let config = new MdDialogConfig();
+    config.viewContainerRef = this.viewContainerRef;
+
+    this.dialogRef = this.dialog.open(PizzaDialog, config);
+
+    this.dialogRef.afterClosed().subscribe(result => {
+      console.log('result: ' + result);
+      this.dialogRef = null;
+    });
+  }
+}
+
+@Component({
+  selector: 'pizza-dialog',
+  template: `
+  <button type="button" (click)="dialogRef.close('yes')">Yes</button>
+  <button type="button" (click)="dialogRef.close('no')">No</button>
+  `
+})
+export class PizzaDialog {
+  constructor(public dialogRef: MdDialogRef<PizzaDialog>) { }
+}
+```
+
+The dialog component should be declared in the list of entry components of the module:
+
+```ts
+@NgModule({
+  declarations: [
+    ...,
+    PizzaDialog
+  ],
+  entryComponents: [
+    ...,
+    PizzaDialog
+  ],
+  ...
+})
+export class AppModule { }
+
+```