docs($route, ng:view): Fix the examples to work on jsfiddle, update docs

2 files changed, 182 insertions, 129 deletions

diff --git a/src/service/route.js b/src/service/route.js
index 50f335a2..3b135e65 100644
--- a/src/service/route.js
+++ b/src/service/route.js
@@ -1,74 +1,22 @@
 'use strict';
 
+
 /**
  * @ngdoc object
- * @name angular.module.ng.$route
- * @requires $location
- * @requires $routeParams
- *
- * @property {Object} current Reference to the current route definition.
- * @property {Array.<Object>} routes Array of all configured routes.
+ * @name angular.module.ng.$routeProvider
+ * @function
  *
  * @description
- * Watches `$location.url()` and tries to map the path to an existing route
- * definition. It is used for deep-linking URLs to controllers and views (HTML partials).
- *
- * The `$route` service is typically used in conjunction with {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
- * widget and the {@link angular.module.ng.$routeParams $routeParams} service.
  *
- * @example
-   This example shows how changing the URL hash causes the <tt>$route</tt>
-   to match a route against the URL, and the <tt>[[ng:include]]</tt> pulls in the partial.
-
-    <doc:example>
-      <doc:source jsfiddle="false">
-        <script>
-          function MainCntl($route, $routeParams, $location) {
-            this.$route = $route;
-            this.$location = $location;
-            this.$routeParams = $routeParams;
-
-            $route.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
-            $route.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
-          }
-
-          function BookCntl($routeParams) {
-            this.name = "BookCntl";
-            this.params = $routeParams;
-          }
-
-          function ChapterCntl($routeParams) {
-            this.name = "ChapterCntl";
-            this.params = $routeParams;
-          }
-        </script>
-
-        <div ng:controller="MainCntl">
-          Choose:
-          <a href="#/Book/Moby">Moby</a> |
-          <a href="#/Book/Moby/ch/1">Moby: Ch1</a> |
-          <a href="#/Book/Gatsby">Gatsby</a> |
-          <a href="#/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a><br/>
-          <pre>$location.path() = {{$location.path()}}</pre>
-          <pre>$route.current.template = {{$route.current.template}}</pre>
-          <pre>$route.current.params = {{$route.current.params}}</pre>
-          <pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
-          <pre>$routeParams = {{$routeParams}}</pre>
-          <hr />
-          <ng:view></ng:view>
-        </div>
-      </doc:source>
-      <doc:scenario>
-      </doc:scenario>
-    </doc:example>
+ * Used for configuring routes. See {@link angular.module.ng.$route $route} for an example.
  */
 function $RouteProvider(){
   var routes = {};
 
   /**
    * @ngdoc method
-   * @name angular.module.ng.$route#when
-   * @methodOf angular.module.ng.$route
+   * @name angular.module.ng.$routeProvider#when
+   * @methodOf angular.module.ng.$routeProvider
    *
    * @param {string} path Route path (matched against `$location.hash`)
    * @param {Object} route Mapping information to be assigned to `$route.current` on route
@@ -97,15 +45,8 @@ function $RouteProvider(){
    *    - `[reloadOnSearch=true]` - {boolean=} - reload route when only $location.search()
    *    changes.
    *
-   *      If the option is set to false and url in the browser changes, then
-   *      $routeUpdate event is emited on the current route scope. You can use this event to
-   *      react to {@link angular.module.ng.$routeParams} changes:
-   *
-   *            function MyCtrl($route, $routeParams) {
-   *              this.$on('$routeUpdate', function() {
-   *                // do stuff with $routeParams
-   *              });
-   *            }
+   *      If the option is set to `false` and url in the browser changes, then
+   *      `$routeUpdate` event is broadcasted on the root scope.
    *
    * @returns {Object} route object
    *
@@ -121,8 +62,8 @@ function $RouteProvider(){
 
   /**
    * @ngdoc method
-   * @name angular.module.ng.$route#otherwise
-   * @methodOf angular.module.ng.$route
+   * @name angular.module.ng.$routeProvider#otherwise
+   * @methodOf angular.module.ng.$routeProvider
    *
    * @description
    * Sets route definition that will be used on route change when no other route definition
@@ -137,6 +78,106 @@ function $RouteProvider(){
 
   this.$get = ['$rootScope', '$location', '$routeParams',
       function( $rootScope,  $location,  $routeParams) {
+
+    /**
+     * @ngdoc object
+     * @name angular.module.ng.$route
+     * @requires $location
+     * @requires $routeParams
+     *
+     * @property {Object} current Reference to the current route definition.
+     * @property {Array.<Object>} routes Array of all configured routes.
+     *
+     * @description
+     * Is used for deep-linking URLs to controllers and views (HTML partials).
+     * It watches `$location.url()` and tries to map the path to an existing route definition.
+     *
+     * You can define routes through {@link angular.module.ng.$routeProvider $routeProvider}'s API.
+     *
+     * The `$route` service is typically used in conjunction with {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
+     * directive and the {@link angular.module.ng.$routeParams $routeParams} service.
+     *
+     * @example
+       This example shows how changing the URL hash causes the `$route` to match a route against the
+       URL, and the `ng:view` pulls in the partial.
+
+       Note that this example is using {@link angular.module.ng.$compileProvide.directive.script inlined templates}
+       to get it working on jsfiddle as well.
+
+      <doc:example module="route">
+        <doc:source>
+          <script type="text/ng-template" id="examples/book.html">
+            controller: {{name}}<br />
+            Book Id: {{params.bookId}}<br />
+          </script>
+
+          <script type="text/ng-template" id="examples/chapter.html">
+            controller: {{name}}<br />
+            Book Id: {{params.bookId}}<br />
+            Chapter Id: {{params.chapterId}}
+          </script>
+
+          <script>
+            angular.module('route', [], function($routeProvider, $locationProvider) {
+              $routeProvider.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
+              $routeProvider.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
+
+              // configure html5 to get links working on jsfiddle
+              $locationProvider.html5Mode(true);
+            });
+
+            function MainCntl($scope, $route, $routeParams, $location) {
+              $scope.$route = $route;
+              $scope.$location = $location;
+              $scope.$routeParams = $routeParams;
+            }
+
+            function BookCntl($scope, $routeParams) {
+              $scope.name = "BookCntl";
+              $scope.params = $routeParams;
+            }
+
+            function ChapterCntl($scope, $routeParams) {
+              $scope.name = "ChapterCntl";
+              $scope.params = $routeParams;
+            }
+          </script>
+
+          <div ng:controller="MainCntl">
+            Choose:
+            <a href="/Book/Moby">Moby</a> |
+            <a href="/Book/Moby/ch/1">Moby: Ch1</a> |
+            <a href="/Book/Gatsby">Gatsby</a> |
+            <a href="/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a> |
+            <a href="/Book/Scarlet">Scarlet Letter</a><br/>
+
+            <ng:view></ng:view>
+            <hr />
+
+            <pre>$location.path() = {{$location.path()}}</pre>
+            <pre>$route.current.template = {{$route.current.template}}</pre>
+            <pre>$route.current.params = {{$route.current.params}}</pre>
+            <pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
+            <pre>$routeParams = {{$routeParams}}</pre>
+          </div>
+        </doc:source>
+        <doc:scenario>
+          it('should load and compile correct template', function() {
+            element('a:contains("Moby: Ch1")').click();
+            var content = element('.doc-example-live ng\\:view').text();
+            expect(content).toMatch(/controller\: ChapterCntl/);
+            expect(content).toMatch(/Book Id\: Moby/);
+            expect(content).toMatch(/Chapter Id\: 1/);
+
+            element('a:contains("Scarlet")').click();
+            content = element('.doc-example-live ng\\:view').text();
+            expect(content).toMatch(/controller\: BookCntl/);
+            expect(content).toMatch(/Book Id\: Scarlet/);
+          });
+        </doc:scenario>
+      </doc:example>
+     */
+
     /**
      * @ngdoc event
      * @name angular.module.ng.$route#$beforeRouteChange
@@ -147,12 +188,6 @@ function $RouteProvider(){
      *
      * @param {Route} next Future route information.
      * @param {Route} current Current route information.
-     *
-     * The `Route` object extends the route definition with the following properties.
-     *
-     *    * `scope` - The instance of the route controller.
-     *    * `params` - The current {@link angular.module.ng.$routeParams params}.
-     *
      */
 
     /**
@@ -165,12 +200,6 @@ function $RouteProvider(){
      *
      * @param {Route} current Current route information.
      * @param {Route} previous Previous route information.
-     *
-     * The `Route` object extends the route definition with the following properties.
-     *
-     *    * `scope` - The instance of the route controller.
-     *    * `params` - The current {@link angular.module.ng.$routeParams params}.
-     *
      */
 
     /**
@@ -196,8 +225,11 @@ function $RouteProvider(){
            * @methodOf angular.module.ng.$route
            *
            * @description
-           * Causes `$route` service to reload (and recreate the `$route.current` scope) upon the next
-           * eval even if {@link angular.module.ng.$location $location} hasn't changed.
+           * Causes `$route` service to reload the current route even if
+           * {@link angular.module.ng.$location $location} hasn't changed.
+           *
+           * As a result of that, {@link angular.module.ng.$compileProvider.directive.ng:view ng:view}
+           * creates new scope, reinstantiates the controller.
            */
           reload: function() {
             dirty++;
diff --git a/src/widgets.js b/src/widgets.js
index 66ea7fef..8bfd232d 100644
--- a/src/widgets.js
+++ b/src/widgets.js
@@ -475,61 +475,82 @@ var ngNonBindableDirective = valueFn({ terminal: true });
  *
  * @description
  * # Overview
- * `ng:view` is a widget that complements the {@link angular.module.ng.$route $route} service by
+ * `ng:view` is a directive that complements the {@link angular.module.ng.$route $route} service by
  * including the rendered template of the current route into the main layout (`index.html`) file.
  * Every time the current route changes, the included view changes with it according to the
  * configuration of the `$route` service.
  *
- * This widget provides functionality similar to {@link angular.module.ng.$compileProvider.directive.ng:include ng:include} when
- * used like this:
- *
- *     <ng:include src="$route.current.template" scope="$route.current.scope"></ng:include>
- *
- *
- * # Advantages
- * Compared to `ng:include`, `ng:view` offers these advantages:
- *
- * - shorter syntax
- * - more efficient execution
- * - doesn't require `$route` service to be available on the root scope
- *
  *
  * @example
     <doc:example module="ngView">
-      <doc:source jsfiddle="false">
-         <script>
-           function BootstrapCtrl() {}
-           function OverviewCtrl() {}
-
-           angular.module('ngView', [])
-             .config(function($routeProvider) {
-               $routeProvider.when('/overview',
-                 { controller: OverviewCtrl,
-                   template: 'partials/guide/dev_guide.overview.html'});
-               $routeProvider.when('/bootstrap',
-                 { controller: BootstrapCtrl,
-                   template: 'partials/guide/dev_guide.bootstrap.auto_bootstrap.html'});
-             });
-         </script>
-         <div>
-           <a href="overview">overview</a> |
-           <a href="bootstrap">bootstrap</a> |
-           <a href="undefined">undefined</a>
-
-           <br/>
-
-           The view is included below:
-           <hr/>
-           <ng:view></ng:view>
-         </div>
+      <doc:source>
+        <script type="text/ng-template" id="examples/book.html">
+          controller: {{name}}<br />
+          Book Id: {{params.bookId}}<br />
+        </script>
+
+        <script type="text/ng-template" id="examples/chapter.html">
+          controller: {{name}}<br />
+          Book Id: {{params.bookId}}<br />
+          Chapter Id: {{params.chapterId}}
+        </script>
+
+        <script>
+          angular.module('ngView', [], function($routeProvider, $locationProvider) {
+            $routeProvider.when('/Book/:bookId', {template: 'examples/book.html', controller: BookCntl});
+            $routeProvider.when('/Book/:bookId/ch/:chapterId', {template: 'examples/chapter.html', controller: ChapterCntl});
+
+            // configure html5 to get links working on jsfiddle
+            $locationProvider.html5Mode(true);
+          });
+
+          function MainCntl($scope, $route, $routeParams, $location) {
+            $scope.$route = $route;
+            $scope.$location = $location;
+            $scope.$routeParams = $routeParams;
+          }
+
+          function BookCntl($scope, $routeParams) {
+            $scope.name = "BookCntl";
+            $scope.params = $routeParams;
+          }
+
+          function ChapterCntl($scope, $routeParams) {
+            $scope.name = "ChapterCntl";
+            $scope.params = $routeParams;
+          }
+        </script>
+
+        <div ng:controller="MainCntl">
+          Choose:
+          <a href="/Book/Moby">Moby</a> |
+          <a href="/Book/Moby/ch/1">Moby: Ch1</a> |
+          <a href="/Book/Gatsby">Gatsby</a> |
+          <a href="/Book/Gatsby/ch/4?key=value">Gatsby: Ch4</a> |
+          <a href="/Book/Scarlet">Scarlet Letter</a><br/>
+
+          <ng:view></ng:view>
+          <hr />
+
+          <pre>$location.path() = {{$location.path()}}</pre>
+          <pre>$route.current.template = {{$route.current.template}}</pre>
+          <pre>$route.current.params = {{$route.current.params}}</pre>
+          <pre>$route.current.scope.name = {{$route.current.scope.name}}</pre>
+          <pre>$routeParams = {{$routeParams}}</pre>
+        </div>
       </doc:source>
       <doc:scenario>
-        it('should load templates', function() {
-          element('.doc-example-live a:contains(overview)').click();
-          expect(element('.doc-example-live ng\\:view').text()).toMatch(/Developer Guide: Overview/);
-
-          element('.doc-example-live a:contains(bootstrap)').click();
-          expect(element('.doc-example-live ng\\:view').text()).toMatch(/Developer Guide: Initializing Angular: Automatic Initialization/);
+        it('should load and compile correct template', function() {
+          element('a:contains("Moby: Ch1")').click();
+          var content = element('.doc-example-live ng\\:view').text();
+          expect(content).toMatch(/controller\: ChapterCntl/);
+          expect(content).toMatch(/Book Id\: Moby/);
+          expect(content).toMatch(/Chapter Id\: 1/);
+
+          element('a:contains("Scarlet")').click();
+          content = element('.doc-example-live ng\\:view').text();
+          expect(content).toMatch(/controller\: BookCntl/);
+          expect(content).toMatch(/Book Id\: Scarlet/);
         });
       </doc:scenario>
     </doc:example>