docs(Location): updating Location docs and adding example

closes #11500

karma-js.conf.js

@@ -48,13 +48,14 @@ module.exports = function(config) {
 
     exclude: [
       'dist/all/@angular/**/e2e_test/**',
-      'dist/all/@angular/router/**',
+      'dist/all/@angular/benchpress/**',
       'dist/all/@angular/compiler-cli/**',
       'dist/all/@angular/compiler/test/aot/**',
-      'dist/all/@angular/benchpress/**',
+      'dist/all/@angular/examples/**/e2e_test/*',
       'dist/all/@angular/language-service/**',
-      'dist/all/angular1_router.js',
+      'dist/all/@angular/router/**',
       'dist/all/@angular/platform-browser/testing/e2e_util.js',
+      'dist/all/angular1_router.js',
       'dist/examples/**/e2e_test/**',
     ],
 

modules/@angular/common/src/location/hash_location_strategy.ts

@@ -17,6 +17,8 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
 
 
 /**
+ * @whatItDoes Use URL hash for storing application location data.
+ * @description
  * `HashLocationStrategy` is a {@link LocationStrategy} used to configure the
  * {@link Location} service to represent its state in the
  * [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax)
@@ -27,8 +29,7 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
  *
  * ### Example
  *
- * {@example common/location/ts/hash_location_strategy/hash_location_strategy_spec.ts
- * region='hash_location_strategy'}
+ * {@example common/location/ts/hash_location_component.ts region='LocationComponent'}
  *
  * @stable
  */

modules/@angular/common/src/location/location.ts

@@ -12,7 +12,8 @@ import {LocationStrategy} from './location_strategy';
 
 
 /**
- * `Location` is a service that applications can use to interact with a browser's URL.
+ * @whatItDoes `Location` is a service that applications can use to interact with a browser's URL.
+ * @description
  * Depending on which {@link LocationStrategy} is used, `Location` will either persist
  * to the URL's path or the URL's hash segment.
  *
@@ -28,19 +29,7 @@ import {LocationStrategy} from './location_strategy';
  * - `/my/app/user/123/` **is not** normalized
  *
  * ### Example
- *
- * ```
- * import {Component} from '@angular/core';
- * import {Location} from '@angular/common';
- *
- * @Component({selector: 'app-component'})
- * class AppCmp {
- *   constructor(location: Location) {
- *     location.go('/foo');
- *   }
- * }
- * ```
- *
+ * {@example common/location/ts/path_location_component.ts region='LocationComponent'}
  * @stable
  */
 @Injectable()

modules/@angular/common/src/location/location_strategy.ts

@@ -12,7 +12,7 @@ import {LocationChangeListener} from './platform_location';
 /**
  * `LocationStrategy` is responsible for representing and reading route state
  * from the browser's URL. Angular provides two strategies:
- * {@link HashLocationStrategy} and {@link PathLocationStrategy} (default).
+ * {@link HashLocationStrategy} and {@link PathLocationStrategy}.
  *
  * This is used under the hood of the {@link Location} service.
  *

modules/@angular/common/src/location/path_location_strategy.ts

@@ -17,14 +17,13 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
 
 
 /**
+ * @whatItDoes Use URL for storing application location data.
+ * @description
  * `PathLocationStrategy` is a {@link LocationStrategy} used to configure the
  * {@link Location} service to represent its state in the
  * [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) of the
  * browser's URL.
  *
- * `PathLocationStrategy` is the default binding for {@link LocationStrategy}
- * provided in {@link ROUTER_PROVIDERS}.
- *
  * If you're using `PathLocationStrategy`, you must provide a {@link APP_BASE_HREF}
  * or add a base element to the document. This URL prefix that will be preserved
  * when generating and recognizing URLs.
@@ -37,6 +36,10 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
  * `location.go('/foo')`, the browser's URL will become
  * `example.com/my/app/foo`.
  *
+ * ### Example
+ *
+ * {@example common/location/ts/path_location_component.ts region='LocationComponent'}
+ *
  * @stable
  */
 @Injectable()

modules/@angular/examples/_common/index.html

@@ -1,11 +1,11 @@
 <!DOCTYPE html>
 <html>
 <head>
-<script type="text/javascript" src="bootstrap.js"></script>
-<script type="text/javascript">
-  System.import('main-dynamic').catch(console.error.bind(console));
-</script>
-<link rel="shortcut icon" href="data:image/x-icon;," type="image/x-icon" />
+  <link rel="shortcut icon" href="data:image/x-icon;," type="image/x-icon" />
+  <script type="text/javascript" src="bootstrap.js"></script>
+  <script type="text/javascript">
+    System.import('main-dynamic').catch(console.error.bind(console));
+  </script>
 </head>
 
 <body>

modules/@angular/examples/common/location/ts/e2e_test/location_component_spec.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+import {browser, by, element, protractor} from 'protractor';
+
+
+function waitForElement(selector: string) {
+  var EC = (<any>protractor).ExpectedConditions;
+  // Waits for the element with id 'abc' to be present on the dom.
+  browser.wait(EC.presenceOf($(selector)), 20000);
+}
+
+describe('Location', () => {
+  afterEach(verifyNoBrowserErrors);
+
+  var URL = '/common/location/ts/#/bar/baz';
+
+  it('should verify paths', () => {
+    browser.get(URL);
+    waitForElement('hash-location');
+    expect(element.all(by.css('path-location code')).get(0).getText())
+        .toEqual('/common/location/ts');
+    expect(element.all(by.css('hash-location code')).get(0).getText()).toEqual('/bar/baz');
+  });
+});

modules/@angular/examples/common/location/ts/hash_location_component.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// #docregion LocationComponent
+import {HashLocationStrategy, Location, LocationStrategy} from '@angular/common';
+import {Component} from '@angular/core';
+
+@Component({
+  selector: 'hash-location',
+  providers: [Location, {provide: LocationStrategy, useClass: HashLocationStrategy}],
+  template: `
+    <h1>HashLocationStrategy</h1>
+    Current URL is: <code>{{location.path()}}</code><br>
+    Normalize: <code>/foo/bar/</code> is: <code>{{location.normalize('foo/bar')}}</code><br>
+  `
+})
+export class HashLocationComponent {
+  location: Location;
+  constructor(location: Location) { this.location = location; }
+}
+// #enddocregion

modules/@angular/examples/common/location/ts/hash_location_strategy/hash_location_strategy_spec.ts

@@ -1,33 +0,0 @@
-/**
- * @license
- * Copyright Google Inc. All Rights Reserved.
- *
- * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://angular.io/license
- */
-// #docplaster
-// #docregion hash_location_strategy
-import {HashLocationStrategy, LocationStrategy} from '@angular/common';
-import {NgModule} from '@angular/core';
-
-// #enddocregion hash_location_strategy
-import {TestBed} from '@angular/core/testing';
-
-// #docregion hash_location_strategy
-@NgModule({providers: [{provide: LocationStrategy, useClass: HashLocationStrategy}]})
-class AppModule {
-}
-// #enddocregion hash_location_strategy
-export function main() {
-  describe('hash_location_strategy examples', () => {
-    let locationStrategy: HashLocationStrategy;
-
-    beforeEach(() => {
-      locationStrategy =
-          TestBed.configureTestingModule({imports: [AppModule]}).get(LocationStrategy);
-    });
-
-    it('hash_location_strategy example works',
-       () => { expect(locationStrategy.prepareExternalUrl('app/foo')).toBe('#app/foo'); });
-  });
-}

modules/@angular/examples/common/location/ts/module.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {APP_BASE_HREF} from '@angular/common';
+import {Component, NgModule} from '@angular/core';
+import {BrowserModule} from '@angular/platform-browser';
+
+import {HashLocationComponent} from './hash_location_component';
+import {PathLocationComponent} from './path_location_component';
+
+@Component({
+  selector: 'example-app',
+  template: `<hash-location></hash-location><path-location></path-location>`
+})
+export class ExampleAppComponent {
+}
+
+@NgModule({
+  declarations: [ExampleAppComponent, PathLocationComponent, HashLocationComponent],
+  providers: [{provide: APP_BASE_HREF, useValue: '/'}],
+  imports: [BrowserModule],
+  bootstrap: [ExampleAppComponent]
+})
+export class AppModule {
+}

modules/@angular/examples/common/location/ts/path_location_component.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// #docregion LocationComponent
+import {Location, LocationStrategy, PathLocationStrategy} from '@angular/common';
+import {Component} from '@angular/core';
+
+@Component({
+  selector: 'path-location',
+  providers: [Location, {provide: LocationStrategy, useClass: PathLocationStrategy}],
+  template: `
+    <h1>PathLocationStrategy</h1>
+    Current URL is: <code>{{location.path()}}</code><br>
+    Normalize: <code>/foo/bar/</code> is: <code>{{location.normalize('foo/bar')}}</code><br>
+  `
+})
+export class PathLocationComponent {
+  location: Location;
+  constructor(location: Location) { this.location = location; }
+}
+// #enddocregion

modules/@angular/examples/platform-browser/dom/debug/ts/debug_element_view_listener/providers.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var core_1 = require('@angular/core');
+var platform_browser_1 = require('@angular/platform-browser');
+var platform_browser_dynamic_1 = require('@angular/platform-browser-dynamic');
+var MyAppComponent = (function () {
+    function MyAppComponent() {
+    }
+    MyAppComponent = __decorate([
+        core_1.Component({ selector: 'my-component' })
+    ], MyAppComponent);
+    return MyAppComponent;
+}());
+// #docregion providers
+var AppModule = (function () {
+    function AppModule() {
+    }
+    AppModule = __decorate([
+        core_1.NgModule({ imports: [platform_browser_1.BrowserModule], bootstrap: [MyAppComponent] })
+    ], AppModule);
+    return AppModule;
+}());
+platform_browser_dynamic_1.platformBrowserDynamic().bootstrapModule(AppModule);
+// #enddocregion

modules/@angular/examples/testing/ts/testing.ts

@@ -6,7 +6,6 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {afterEach, beforeEach, beforeEachProviders, describe, inject, it, xdescribe, xit} from '@angular/core/testing/testing_internal';
 
 let db: any;
 class MyService {}
@@ -70,16 +69,6 @@ describe('some component', () => {
 });
 // #enddocregion
 
-// #docregion beforeEachProviders
-describe('some component', () => {
-  beforeEachProviders(() => [{provide: MyService, useClass: MyMockService}]);
-  it('uses MyService', inject(
-                           [MyService], (service: MyMockService) => {
-                                            // service is an instance of MyMockService.
-                                        }));
-});
-// #enddocregion
-
 // #docregion afterEach
 describe('some component', () => {
   afterEach((done: Function) => { db.reset().then((_: any) => done()); });

modules/@angular/examples/tsconfig-build.json

@@ -5,6 +5,7 @@
     "stripInternal": true,
     "experimentalDecorators": true,
     "noImplicitAny": true,
+    "emitDecoratorMetadata": true,
     "module": "commonjs",
     "moduleResolution": "node",
     "outDir": "../../../dist/examples",
@@ -21,11 +22,7 @@
     "types": ["jasmine", "node", "angularjs", "systemjs"]
   },
   "include": [
-    "./_common/*.ts",
-    "./**/module.ts",
-    "./**/test/*.ts",
-    "./**/e2e_test/*.ts",
-    "../../system.d.ts",
+    "./**/*.ts",
     "../../../node_modules/zone.js/dist/zone.js.d.ts",
     // TODO(i): we can't use protractor's built-in typings because they contain lots of ambient definitions
     "../../../node_modules/@types/protractor/index.d.ts"

protractor-examples-e2e.conf.js

@@ -9,6 +9,9 @@
 // Make sure that the command line is read as the first thing
 // as this could exit node if the help script should be printed.
 require('./dist/all/e2e_util/e2e_util').readCommandLine();
+require('reflect-metadata');
+
+Error.stackTraceLimit = 9999;
 
 var BROWSER_OPTIONS = {
   LocalChrome: {'browserName': 'chrome'},
@@ -24,7 +27,9 @@ var BROWSER_OPTIONS = {
 exports.config = {
   onPrepare: function() { beforeEach(function() { browser.ignoreSynchronization = false; }); },
   allScriptsTimeout: 11000,
-  specs: ['dist/examples/**/e2e_test/*_spec.js'],
+  specs: [
+    'dist/examples/**/e2e_test/*_spec.js'
+  ],
   capabilities: process.env.TRAVIS ? BROWSER_OPTIONS.ChromeOnTravis : BROWSER_OPTIONS.LocalChrome,
   directConnect: true,
   baseUrl: 'http://localhost:8001/',

tools/cjs-jasmine/index.ts

@@ -52,6 +52,7 @@ var specFiles: any =
                      cwd: distAll,
                      ignore: [
                        // the following code and tests are not compatible with CJS/node environment
+                       '@angular/examples/**',
                        '@angular/platform-browser/**',
                        '@angular/platform-browser-dynamic/**',
                        '@angular/core/test/zone/**',