feat(Angular.js): add externs file for Closure Compiler

This adds an (incomplete) externs file for use with the Closure Compiler. Users can pass this as -extern to the compiler pass to get type checking and protect their AngularJS use against property renaming in advanced compilation mode.
revert(validate-commit-msg): fix incorrect comment
2013-10-30 14:59:33 -07:00 · 2013-10-21 16:27:04 +01:00 · 2013-10-11 12:59:39 +01:00 · 2013-10-11 12:58:22 +01:00 · 2013-10-10 18:22:52 +01:00 · 2013-10-10 18:22:51 +01:00
961 changed files with 95299 additions and 28452 deletions
@@ -0,0 +1,4 @@
+{
+  "directory": "bower_components",
+  "json": "bower.json"
+}
@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ui.externaltools.ProgramBuilderLaunchConfigurationType">
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_BUILDER_ENABLED" value="true"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_BUILD_SCOPE" value="${working_set:&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&#10;&lt;launchConfigurationWorkingSet editPageId=&quot;org.eclipse.ui.resourceWorkingSetPage&quot; factoryID=&quot;org.eclipse.ui.internal.WorkingSetFactory&quot; id=&quot;1262905463390_2&quot; label=&quot;workingSet&quot; name=&quot;workingSet&quot;&gt;&#10;&lt;item factoryID=&quot;org.eclipse.ui.internal.model.ResourceFactory&quot; path=&quot;/angular.js/test&quot; type=&quot;2&quot;/&gt;&#10;&lt;item factoryID=&quot;org.eclipse.ui.internal.model.ResourceFactory&quot; path=&quot;/angular.js/src&quot; type=&quot;2&quot;/&gt;&#10;&lt;/launchConfigurationWorkingSet&gt;}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/angular.js}/test.sh"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="full,incremental,auto,"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/angular.js}"/>
-</launchConfiguration>
@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ui.externaltools.ProgramBuilderLaunchConfigurationType">
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_BUILDER_ENABLED" value="false"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_BUILD_SCOPE" value="${working_set:&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&#10;&lt;resources&gt;&#10;&lt;item path=&quot;/angular.js/perf&quot; type=&quot;2&quot;/&gt;&#10;&lt;item path=&quot;/angular.js/src&quot; type=&quot;2&quot;/&gt;&#10;&lt;/resources&gt;}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/angular.js/perf.sh}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="full,incremental,auto,"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/angular.js}"/>
-</launchConfiguration>
@@ -1,11 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ui.externaltools.ProgramBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&#10;&lt;resources&gt;&#10;&lt;item path=&quot;/angular.js/build&quot; type=&quot;2&quot;/&gt;&#10;&lt;/resources&gt;}"/>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_BUILDER_ENABLED" value="true"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_BUILD_SCOPE" value="${working_set:&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&#10;&lt;resources&gt;&#10;&lt;item path=&quot;/angular.js/docs&quot; type=&quot;2&quot;/&gt;&#10;&lt;item path=&quot;/angular.js/src&quot; type=&quot;2&quot;/&gt;&#10;&lt;/resources&gt;}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/angular.js/gen_docs.sh}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="full,incremental,auto,"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/angular.js}"/>
-</launchConfiguration>
@@ -1,7 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ui.externaltools.ProgramLaunchConfigurationType">
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;&#10;&lt;resources&gt;&#10;&lt;item path=&quot;/angular.js/docs&quot; type=&quot;2&quot;/&gt;&#10;&lt;/resources&gt;}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LAUNCH_CONFIGURATION_BUILD_SCOPE" value="${none}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/angular.js/gen_docs.sh}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/angular.js}"/>
-</launchConfiguration>
@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ui.externaltools.ProgramLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/angular.js/lib/jsl/jsl}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_TOOL_ARGUMENTS" value="-conf lib/jsl/jsl.default.conf"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/angular.js}"/>
-</launchConfiguration>
@@ -10,6 +10,7 @@ performance/temp*.html
 *~
 angular.js.tmproj
 node_modules
-jsTestDriver*.conf
 angular.xcodeproj
 .idea
+libpeerconnection.log
+npm-debug.log
@@ -1,47 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
-	<name>angular.js</name>
-	<comment></comment>
-	<projects>
-	</projects>
-	<buildSpec>
-		<buildCommand>
-			<name>org.eclipse.wst.jsdt.core.javascriptValidator</name>
-			<arguments>
-			</arguments>
-		</buildCommand>
-		<buildCommand>
-			<name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
-			<triggers>auto,full,incremental,</triggers>
-			<arguments>
-				<dictionary>
-					<key>LaunchConfigHandle</key>
-					<value>&lt;project&gt;/.externalToolBuilders/docs.launch</value>
-				</dictionary>
-			</arguments>
-		</buildCommand>
-		<buildCommand>
-			<name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
-			<triggers>auto,full,incremental,</triggers>
-			<arguments>
-				<dictionary>
-					<key>LaunchConfigHandle</key>
-					<value>&lt;project&gt;/.externalToolBuilders/JSTD_Tests.launch</value>
-				</dictionary>
-			</arguments>
-		</buildCommand>
-		<buildCommand>
-			<name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
-			<triggers>auto,full,incremental,</triggers>
-			<arguments>
-				<dictionary>
-					<key>LaunchConfigHandle</key>
-					<value>&lt;project&gt;/.externalToolBuilders/JSTD_perf.launch</value>
-				</dictionary>
-			</arguments>
-		</buildCommand>
-	</buildSpec>
-	<natures>
-		<nature>org.eclipse.wst.jsdt.core.jsNature</nature>
-	</natures>
-</projectDescription>
@@ -1,10 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<classpath>
-	<classpathentry excluding="test/" kind="src" path="src"/>
-	<classpathentry excluding="docs-data.js|docs-scenario.js" kind="src" path="docs"/>
-	<classpathentry excluding="test/" kind="src" path="test"/>
-	<classpathentry kind="src" path="test/test"/>
-	<classpathentry kind="con" path="org.eclipse.wst.jsdt.launching.JRE_CONTAINER"/>
-	<classpathentry kind="con" path="org.eclipse.wst.jsdt.launching.baseBrowserLibrary"/>
-	<classpathentry kind="output" path=""/>
-</classpath>
@@ -1,16 +0,0 @@
-#Mon Jan 24 10:31:47 PST 2011
-activeContentFilterList=*.makefile,makefile,*.Makefile,Makefile,Makefile.*,*.mk,MANIFEST.MF
-addNewLine=true
-convertActionOnSaave=AnyEdit.CnvrtTabToSpaces
-eclipse.preferences.version=1
-inActiveContentFilterList=
-javaTabWidthForJava=true
-org.eclipse.jdt.ui.editor.tab.width=2
-projectPropsEnabled=false
-removeTrailingSpaces=true
-replaceAllSpaces=false
-replaceAllTabs=false
-saveAndAddLine=true
-saveAndConvert=true
-saveAndTrim=true
-useModulo4Tabs=false
@@ -1 +0,0 @@
-org.eclipse.wst.jsdt.launching.JRE_CONTAINER
@@ -1 +0,0 @@
-Global
@@ -0,0 +1,19 @@
+language: node_js
+node_js:
+  - 0.10
+
+env:
+  global:
+    - SAUCE_USERNAME=angular-ci
+    - SAUCE_ACCESS_KEY=9b988f434ff8-fbca-8aa4-4ae3-35442987
+    - SAUCE_CONNECT_READY_FILE=/tmp/sauce-connect-ready
+
+before_script:
+  - export SAUCE_ACCESS_KEY=`echo $SAUCE_ACCESS_KEY | rev`
+  - ./lib/sauce/sauce_connect_setup.sh
+  - npm install -g grunt-cli
+  - grunt ci-checks package
+  - ./lib/sauce/sauce_connect_block.sh
+
+script:
+  - grunt parallel:travis --reporters dots --browsers SL_Chrome
@@ -0,0 +1,32 @@
+## Submitting issues
+
+If you have questions about how to use AngularJS, please direct these to the
+[Google Group][groups] discussion list or [StackOverflow][stackoverflow]. We are
+also available on [IRC][irc].
+
+### Guidelines
+
+* Search the archive first, it's likely that your question was already answered.
+* A live example demonstrating your problem or question, will get an answer faster.
+* Create one using this [template][template]
+* If you get help, help others. Good karma rulez!
+
+If your issue appears to be a bug, and hasn't been reported, open a new issue.
+Help us to maximize the effort we can spend fixing issues and adding new
+features, by not reporting duplicate issues.
+
+[stackoverflow]: http://stackoverflow.com/questions/tagged/angularjs
+[groups]: https://groups.google.com/forum/?fromgroups#!forum/angular
+[irc]: http://webchat.freenode.net/?channels=angularjs&uio=d4
+[template]: http://plnkr.co/edit/gist:3510140
+
+## Contributing to Source Code
+
+We'd love for you to contribute to our source code and to make AngularJS even
+better than it is today!
+
+ Please read the [contribution guidelines][contribute] to learn about how to submit code as well as
+ other useful info like how to build and test AngularJS code.
+
+[list]: https://groups.google.com/forum/?fromgroups#!forum/angular
+[contribute]: http://docs.angularjs.org/misc/contribute
@@ -0,0 +1,228 @@
+var files = require('./angularFiles').files;
+var util = require('./lib/grunt/utils.js');
+
+module.exports = function(grunt) {
+  //grunt plugins
+  grunt.loadNpmTasks('grunt-contrib-clean');
+  grunt.loadNpmTasks('grunt-contrib-copy');
+  grunt.loadNpmTasks('grunt-contrib-connect');
+  grunt.loadNpmTasks('grunt-contrib-compress');
+  grunt.loadNpmTasks('grunt-ddescribe-iit');
+  grunt.loadNpmTasks('grunt-merge-conflict');
+  grunt.loadNpmTasks('grunt-parallel');
+  grunt.loadTasks('lib/grunt');
+
+  var NG_VERSION = util.getVersion();
+  var dist = 'angular-'+ NG_VERSION.full;
+
+
+  //global beforeEach
+  util.init();
+
+
+  //config
+  grunt.initConfig({
+    NG_VERSION: NG_VERSION,
+
+    parallel: {
+      travis: {
+        options: {
+          stream: true,
+        },
+        tasks: [
+          util.parallelTask('test:modules'),
+          util.parallelTask('test:jquery'),
+          util.parallelTask('test:jqlite'),
+          util.parallelTask('test:e2e')
+        ]
+      }
+    },
+
+    connect: {
+      devserver: {
+        options: {
+          port: 8000,
+          hostname: '0.0.0.0',
+          base: '.',
+          keepalive: true,
+          middleware: function(connect, options){
+            return [
+              //uncomment to enable CSP
+              // util.csp(),
+              util.rewrite(),
+              connect.favicon('images/favicon.ico'),
+              connect.static(options.base),
+              connect.directory(options.base)
+            ];
+          }
+        }
+      },
+      testserver: {
+        options: {
+          // We use end2end task (which does not start the webserver)
+          // and start the webserver as a separate process (in travis_build.sh)
+          // to avoid https://github.com/joyent/libuv/issues/826
+          port: 8000,
+          hostname: '0.0.0.0',
+          middleware: function(connect, options){
+            return [
+              function(req, resp, next) {
+                // cache get requests to speed up tests on travis
+                if (req.method === 'GET') {
+                  resp.setHeader('Cache-control', 'public, max-age=3600');
+                }
+
+                next();
+              },
+              connect.favicon('images/favicon.ico'),
+              connect.static(options.base)
+            ];
+          }
+        }
+      }
+    },
+
+
+    test: {
+      jqlite: 'karma-jqlite.conf.js',
+      jquery: 'karma-jquery.conf.js',
+      modules: 'karma-modules.conf.js',
+      //NOTE run grunt test:e2e instead and it will start a webserver for you
+      end2end: 'karma-e2e.conf.js'
+    },
+
+
+    autotest: {
+      jqlite: 'karma-jqlite.conf.js',
+      jquery: 'karma-jquery.conf.js'
+    },
+
+
+    clean: {build: ['build']},
+
+
+    build: {
+      scenario: {
+        dest: 'build/angular-scenario.js',
+        src: [
+          'lib/jquery/jquery.js',
+          util.wrap([files['angularSrc'], files['angularScenario']], 'ngScenario/angular')
+        ],
+        styles: {
+          css: ['css/angular.css', 'css/angular-scenario.css']
+        }
+      },
+      angular: {
+        dest: 'build/angular.js',
+        src: util.wrap([files['angularSrc']], 'angular'),
+        styles: {
+          css: ['css/angular.css'],
+          minify: true
+        }
+      },
+      loader: {
+        dest: 'build/angular-loader.js',
+        src: util.wrap(['src/loader.js'], 'loader')
+      },
+      mocks: {
+        dest: 'build/angular-mocks.js',
+        src: ['src/ngMock/angular-mocks.js'],
+        strict: false
+      },
+      sanitize: {
+        dest: 'build/angular-sanitize.js',
+        src: util.wrap([
+          'src/ngSanitize/sanitize.js',
+          'src/ngSanitize/directive/ngBindHtml.js',
+          'src/ngSanitize/filter/linky.js',
+        ], 'module')
+      },
+      resource: {
+        dest: 'build/angular-resource.js',
+        src: util.wrap(['src/ngResource/resource.js'], 'module')
+      },
+      cookies: {
+        dest: 'build/angular-cookies.js',
+        src: util.wrap(['src/ngCookies/cookies.js'], 'module')
+      },
+      bootstrap: {
+        dest: 'build/angular-bootstrap.js',
+        src: util.wrap(['src/bootstrap/bootstrap.js'], 'module')
+      },
+      bootstrapPrettify: {
+        dest: 'build/angular-bootstrap-prettify.js',
+        src: util.wrap(['src/bootstrap/bootstrap-prettify.js', 'src/bootstrap/google-prettify/prettify.js'], 'module'),
+        styles: {
+          css: ['src/bootstrap/google-prettify/prettify.css'],
+          minify: true
+        }
+      }
+    },
+
+
+    min: {
+      angular: 'build/angular.js',
+      cookies: 'build/angular-cookies.js',
+      loader: 'build/angular-loader.js',
+      resource: 'build/angular-resource.js',
+      sanitize: 'build/angular-sanitize.js',
+      bootstrap: 'build/angular-bootstrap.js',
+      bootstrapPrettify: 'build/angular-bootstrap-prettify.js',
+    },
+
+
+    docs: {
+      process: ['build/docs/*.html', 'build/docs/.htaccess']
+    },
+
+
+    "ddescribe-iit": {
+      files: [
+        'test/**/*.js',
+        '!test/ngScenario/DescribeSpec.js'
+      ]
+    },
+
+    "merge-conflict": {
+      files: [
+        'src/**/*',
+        'test/**/*',
+        'docs/**/*',
+        'css/**/*'
+      ]
+    },
+
+
+    copy: {
+      i18n: {
+        files: [
+          { src: 'src/ngLocale/**', dest: 'build/i18n/', expand: true, flatten: true }
+        ]
+      }
+    },
+
+
+    compress: {
+      build: {
+        options: {archive: 'build/' + dist +'.zip', mode: 'zip'},
+        src: ['**'], cwd: 'build', expand: true, dot: true, dest: dist + '/'
+      }
+    },
+
+
+    write: {
+      versionTXT: {file: 'build/version.txt', val: NG_VERSION.full},
+      versionJSON: {file: 'build/version.json', val: JSON.stringify(NG_VERSION)}
+    }
+  });
+
+
+  //alias tasks
+  grunt.registerTask('test:unit', ['test:jqlite', 'test:jquery', 'test:modules']);
+  grunt.registerTask('minify', ['clean', 'build', 'minall']);
+  grunt.registerTask('test:e2e', ['connect:testserver', 'test:end2end']);
+  grunt.registerTask('webserver', ['connect:devserver']);
+  grunt.registerTask('package', ['clean', 'buildall', 'minall', 'docs', 'copy', 'write', 'compress']);
+  grunt.registerTask('ci-checks', ['ddescribe-iit', 'merge-conflict']);
+  grunt.registerTask('default', ['package']);
+};
@@ -1,6 +1,6 @@
 The MIT License

-Copyright (c) 2010 Adam Abrons and Misko Hevery http://getangular.com
+Copyright (c) 2010-2012 Google, Inc. http://angularjs.org

 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -1,19 +1,40 @@
 AngularJS
 =========

-* Web site: http://angularjs.org
-* Tutorial: http://docs.angularjs.org/#!/tutorial
-* API Docs: http://docs.angularjs.org
-* Developer Guide: http://docs.angularjs.org/#!/guide
+AngularJS lets you write client-side web applications as if you had a smarter browser.  It lets you
+use good old HTML (or HAML, Jade and friends!) as your template language and lets you extend HTML’s
+syntax to express your application’s components clearly and succinctly.  It automatically
+synchronizes data from your UI (view) with your JavaScript objects (model) through 2-way data
+binding. To help you structure your application better and make it easy to test, AngularJS teaches
+the browser how to do dependency injection and inversion of control. Oh yeah and it also helps with
+server-side communication, taming async callbacks with promises and deferreds; and make client-side
+navigation and deeplinking with hashbang urls or HTML5 pushState a piece of cake. The best of all:
+it makes development fun!

-Compiling
+* Web site: http://angularjs.org
+* Tutorial: http://docs.angularjs.org/tutorial
+* API Docs: http://docs.angularjs.org/api
+* Developer Guide: http://docs.angularjs.org/guide
+* Contribution guidelines: http://docs.angularjs.org/misc/contribute
+* Dashboard: http://dashboard.angularjs.org
+
+Building AngularJS
 ---------
-    rake compile
+[Once you have your environment setup](http://docs.angularjs.org/misc/contribute) just run:
+
+    grunt package
+

 Running Tests
 -------------
-    ./server.sh                          # start the server
-    open http://localhost:9876/capture   # capture browser
-    ./test.sh                            # run all unit tests
+To execute all unit tests, use:

+    grunt test:unit

+To execute end-to-end (e2e) tests, use:
+
+    grunt package
+    grunt test:e2e
+
+To learn more about the grunt tasks, run `grunt --help` and also read our
+[contribution guidelines](http://docs.angularjs.org/misc/contribute).
@@ -1,338 +0,0 @@
-require 'yaml'
-include FileUtils
-
-content = File.open('angularFiles.js', 'r') {|f| f.read }
-files = eval(content.gsub(/\};(\s|\S)*/, '}').gsub(/angularFiles = /, '').gsub(/:/, '=>'));
-
-BUILD_DIR = 'build'
-
-task :default => [:compile, :test]
-
-
-desc 'Init the build workspace'
-task :init do
-  FileUtils.mkdir(BUILD_DIR) unless File.directory?(BUILD_DIR)
-
-  v = YAML::load( File.open( 'version.yaml' ) )
-  match = v['version'].match(/^([^-]*)(-snapshot)?$/)
-
-  NG_VERSION = Struct.new(:full, :major, :minor, :dot, :codename).
-                      new(match[1] + (match[2] ? ('-' + %x(git rev-parse HEAD)[0..7]) : ''),
-                          match[1].split('.')[0],
-                          match[1].split('.')[1],
-                          match[1].split('.')[2].sub(/\D+.*$/, ''),
-                          v['codename'])
-end
-
-
-desc 'Clean Generated Files'
-task :clean do
-  FileUtils.rm_r(BUILD_DIR, :force => true)
-  FileUtils.mkdir(BUILD_DIR)
-end
-
-
-desc 'Compile Scenario'
-task :compile_scenario => :init do
-
-  deps = [
-      'lib/jquery/jquery.js',
-      'src/scenario/angular.prefix',
-      files['angularSrc'],
-      files['angularScenario'],
-      'src/scenario/angular.suffix',
-  ]
-
-  concat = 'cat ' + deps.flatten.join(' ')
-
-  File.open(path_to('angular-scenario.js'), 'w') do |f|
-    f.write(%x{#{concat}}.gsub('"NG_VERSION_FULL"', NG_VERSION.full))
-    f.write(gen_css('css/angular.css') + "\n")
-    f.write(gen_css('css/angular-scenario.css'))
-  end
-end
-
-desc 'Compile JSTD Scenario Adapter'
-task :compile_jstd_scenario_adapter => :init do
-
-  deps = [
-      'src/jstd-scenario-adapter/angular.prefix',
-      'src/jstd-scenario-adapter/Adapter.js',
-      'src/jstd-scenario-adapter/angular.suffix',
-  ]
-
-  concat = 'cat ' + deps.flatten.join(' ')
-
-  File.open(path_to('jstd-scenario-adapter.js'), 'w') do |f|
-    f.write(%x{#{concat}}.gsub('"NG_VERSION_FULL"', NG_VERSION.full))
-  end
-
-  # TODO(vojta) use jstd configuration when implemented
-  # (instead of including jstd-adapter-config.js)
-  File.open(path_to('jstd-scenario-adapter-config.js'), 'w') do |f|
-    f.write("/**\r\n" +
-            " * Configuration for jstd scenario adapter \n */\n" +
-            "var jstdScenarioAdapter = {\n  relativeUrlPrefix: '/build/docs/'\n};\n")
-  end
-end
-
-
-desc 'Compile JavaScript'
-task :compile => [:init, :compile_scenario, :compile_jstd_scenario_adapter] do
-
-  deps = [
-      'src/angular.prefix',
-      files['angularSrc'],
-      'src/angular.suffix',
-  ]
-
-  File.open(path_to('angular.js'), 'w') do |f|
-    concat = 'cat ' + deps.flatten.join(' ')
-
-    content = %x{#{concat}}.
-              gsub('"NG_VERSION_FULL"', NG_VERSION.full).
-              gsub('"NG_VERSION_MAJOR"', NG_VERSION.major).
-              gsub('"NG_VERSION_MINOR"', NG_VERSION.minor).
-              gsub('"NG_VERSION_DOT"', NG_VERSION.dot).
-              gsub('"NG_VERSION_CODENAME"', NG_VERSION.codename).
-              gsub(/^\s*['"]use strict['"];?\s*$/, ''). # remove all file-specific strict mode flags
-              gsub(/'USE STRICT'/, "'use strict'")      # rename the placeholder in angular.prefix
-
-    f.write(content)
-    f.write(gen_css('css/angular.css', true))
-  end
-
-  %x(java -jar lib/closure-compiler/compiler.jar \
-        --compilation_level SIMPLE_OPTIMIZATIONS \
-        --language_in ECMASCRIPT5_STRICT \
-        --js #{path_to('angular.js')} \
-        --js_output_file #{path_to('angular.min.js')})
-
-  FileUtils.cp_r 'i18n/locale', path_to('i18n')
-
-  File.open(path_to('angular-loader.js'), 'w') do |f|
-    concat = 'cat ' + [
-      'src/loader.prefix',
-      'src/loader.js',
-      'src/loader.suffix'].flatten.join(' ')
-
-    content = %x{#{concat}}.
-              gsub('"NG_VERSION_FULL"', NG_VERSION.full).
-              gsub(/^\s*['"]use strict['"];?\s*$/, '') # remove all file-specific strict mode flags
-
-    f.write(content)
-  end
-
-  %x(java -jar lib/closure-compiler/compiler.jar \
-        --compilation_level SIMPLE_OPTIMIZATIONS \
-        --language_in ECMASCRIPT5_STRICT \
-        --js #{path_to('angular-loader.js')} \
-        --js_output_file #{path_to('angular-loader.min.js')})
-
-
-end
-
-
-desc 'Generate docs'
-task :docs => [:init] do
-  `node docs/src/gen-docs.js`
-  File.open(path_to('docs/.htaccess'), File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('"NG_VERSION_FULL"', NG_VERSION.full)
-  end
-end
-
-
-desc 'Create angular distribution'
-task :package => [:clean, :compile, :docs] do
-  tarball = "angular-#{NG_VERSION.full}.tgz"
-
-  pkg_dir = path_to("pkg/angular-#{NG_VERSION.full}")
-  FileUtils.rm_r(path_to('pkg'), :force => true)
-  FileUtils.mkdir_p(pkg_dir)
-
-  ['src/angular-mocks.js',
-    path_to('angular.js'),
-    path_to('angular-loader.js'),
-    path_to('angular.min.js'),
-    path_to('angular-loader.min.js'),
-    path_to('angular-scenario.js'),
-    path_to('jstd-scenario-adapter.js'),
-    path_to('jstd-scenario-adapter-config.js'),
-  ].each do |src|
-    dest = src.gsub(/^[^\/]+\//, '').gsub(/((\.min)?\.js)$/, "-#{NG_VERSION.full}\\1")
-    FileUtils.cp(src, pkg_dir + '/' + dest)
-  end
-
-  FileUtils.cp_r path_to('i18n'), "#{pkg_dir}/i18n-#{NG_VERSION.full}"
-  FileUtils.cp_r path_to('docs'), "#{pkg_dir}/docs-#{NG_VERSION.full}"
-
-  File.open("#{pkg_dir}/angular-mocks-#{NG_VERSION.full}.js", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('"NG_VERSION_FULL"', NG_VERSION.full)
-  end
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-jq.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-nocache.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-jq-nocache.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-debug.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('../angular.js', "../angular-#{NG_VERSION.full}.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-jq-debug.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('../angular.js', "../angular-#{NG_VERSION.full}.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/docs-scenario.html", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular-scenario.js', "angular-scenario-#{NG_VERSION.full}.js")
-  end
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/appcache.manifest", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-  File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/appcache-offline.manifest", File::RDWR) do |f|
-    text = f.read
-    f.truncate 0
-    f.rewind
-    f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
-                 sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
-  end
-
-
-  %x(tar -czf #{path_to(tarball)} -C #{path_to('pkg')} .)
-
-  FileUtils.cp path_to(tarball), pkg_dir
-  FileUtils.mv pkg_dir, path_to(['pkg', NG_VERSION.full])
-
-  puts "Package created: #{path_to(tarball)}"
-end
-
-
-namespace :server do
-
-  desc 'Run JsTestDriver Server'
-  task :start do
-    sh %x(java -jar lib/jstestdriver/JsTestDriver.jar --browser open --port 9876)
-  end
-
-  desc 'Run JavaScript tests against the server'
-  task :test do
-    sh %(java -jar lib/jstestdriver/JsTestDriver.jar --tests all)
-  end
-
-end
-
-
-desc 'Run JavaScript tests'
-task :test do
-  sh %(java -jar lib/jstestdriver/JsTestDriver.jar --tests all --browser open --port 9876)
-end
-
-
-desc 'Lint'
-task :lint do
-  out = %x(lib/jsl/jsl -conf lib/jsl/jsl.default.conf)
-  print out
-end
-
-
-desc 'push_angularjs'
-task :push_angularjs => :compile do
-  sh %(cat angularjs.ftp | ftp -N angularjs.netrc angularjs.org)
-end
-
-
-
-###################
-# utility methods #
-###################
-
-
-##
-# generates css snippet from a given files and optionally applies simple minification rules
-#
-def gen_css(cssFile, minify = false)
-  css = ''
-  File.open(cssFile, 'r') do |f|
-    css = f.read
-  end
-
-  if minify
-    css.gsub! /\n/, ''
-    css.gsub! /\/\*.*?\*\//, ''
-    css.gsub! /:\s+/, ':'
-    css.gsub! /\s*\{\s*/, '{'
-    css.gsub! /\s*\}\s*/, '}'
-    css.gsub! /\s*\,\s*/, ','
-    css.gsub! /\s*\;\s*/, ';'
-  end
-
-  #escape for js
-  css.gsub! /\\/, "\\\\\\"
-  css.gsub! /'/, "\\\\'"
-  css.gsub! /\n/, "\\n"
-
-  return %Q{angular.element(document).find('head').append('<style type="text/css">#{css}</style>');}
-end
-
-
-##
-# returns path to the file in the build directory
-#
-def path_to(filename)
-  return File.join(BUILD_DIR, *filename)
-end
@@ -3,189 +3,188 @@ angularFiles = {
    'src/Angular.js',
    'src/loader.js',
    'src/AngularPublic.js',
-    'src/JSON.js',
-    'src/Injector.js',
-    'src/Resource.js',
    'src/jqLite.js',
    'src/apis.js',
-    'src/service/anchorScroll.js',
-    'src/service/browser.js',
-    'src/service/cacheFactory.js',
-    'src/service/compiler.js',
-    'src/service/controller.js',
-    'src/service/cookieStore.js',
-    'src/service/cookies.js',
-    'src/service/defer.js',
-    'src/service/document.js',
-    'src/service/exceptionHandler.js',
-    'src/service/filter.js',
-    'src/service/filter/filter.js',
-    'src/service/filter/filters.js',
-    'src/service/filter/limitTo.js',
-    'src/service/filter/orderBy.js',
-    'src/service/interpolate.js',
-    'src/service/location.js',
-    'src/service/log.js',
-    'src/service/resource.js',
-    'src/service/parse.js',
-    'src/service/q.js',
-    'src/service/route.js',
-    'src/service/routeParams.js',
-    'src/service/scope.js',
-    'src/service/sanitize.js',
-    'src/service/sniffer.js',
-    'src/service/window.js',
-    'src/service/http.js',
-    'src/service/httpBackend.js',
-    'src/service/locale.js',
-    'src/directive/directives.js',
-    'src/directive/a.js',
-    'src/directive/booleanAttrDirs.js',
-    'src/directive/form.js',
-    'src/directive/input.js',
-    'src/directive/ngBind.js',
-    'src/directive/ngClass.js',
-    'src/directive/ngCloak.js',
-    'src/directive/ngController.js',
-    'src/directive/ngEventDirs.js',
-    'src/directive/ngInclude.js',
-    'src/directive/ngInit.js',
-    'src/directive/ngNonBindable.js',
-    'src/directive/ngPluralize.js',
-    'src/directive/ngRepeat.js',
-    'src/directive/ngShowHide.js',
-    'src/directive/ngStyle.js',
-    'src/directive/ngSwitch.js',
-    'src/directive/ngTransclude.js',
-    'src/directive/ngView.js',
-    'src/directive/script.js',
-    'src/directive/select.js',
-    'src/directive/style.js'
+
+    'src/auto/injector.js',
+
+    'src/ng/anchorScroll.js',
+    'src/ng/browser.js',
+    'src/ng/cacheFactory.js',
+    'src/ng/compile.js',
+    'src/ng/controller.js',
+    'src/ng/document.js',
+    'src/ng/exceptionHandler.js',
+    'src/ng/interpolate.js',
+    'src/ng/location.js',
+    'src/ng/log.js',
+    'src/ng/parse.js',
+    'src/ng/q.js',
+    'src/ng/route.js',
+    'src/ng/routeParams.js',
+    'src/ng/rootScope.js',
+    'src/ng/sniffer.js',
+    'src/ng/window.js',
+    'src/ng/http.js',
+    'src/ng/httpBackend.js',
+    'src/ng/locale.js',
+    'src/ng/timeout.js',
+
+    'src/ng/filter.js',
+    'src/ng/filter/filter.js',
+    'src/ng/filter/filters.js',
+    'src/ng/filter/limitTo.js',
+    'src/ng/filter/orderBy.js',
+
+    'src/ng/directive/directives.js',
+    'src/ng/directive/a.js',
+    'src/ng/directive/booleanAttrs.js',
+    'src/ng/directive/form.js',
+    'src/ng/directive/input.js',
+    'src/ng/directive/ngBind.js',
+    'src/ng/directive/ngClass.js',
+    'src/ng/directive/ngCloak.js',
+    'src/ng/directive/ngController.js',
+    'src/ng/directive/ngCsp.js',
+    'src/ng/directive/ngEventDirs.js',
+    'src/ng/directive/ngInclude.js',
+    'src/ng/directive/ngInit.js',
+    'src/ng/directive/ngNonBindable.js',
+    'src/ng/directive/ngPluralize.js',
+    'src/ng/directive/ngRepeat.js',
+    'src/ng/directive/ngShowHide.js',
+    'src/ng/directive/ngStyle.js',
+    'src/ng/directive/ngSwitch.js',
+    'src/ng/directive/ngTransclude.js',
+    'src/ng/directive/ngView.js',
+    'src/ng/directive/script.js',
+    'src/ng/directive/select.js',
+    'src/ng/directive/style.js'
+  ],
+
+  'angularSrcModules': [
+    'src/ngCookies/cookies.js',
+    'src/ngResource/resource.js',
+    'src/ngSanitize/sanitize.js',
+    'src/ngSanitize/directive/ngBindHtml.js',
+    'src/ngSanitize/filter/linky.js',
+    'src/ngMock/angular-mocks.js',
+
+    'src/bootstrap/bootstrap.js'
  ],

  'angularScenario': [
-    'src/scenario/Scenario.js',
-    'src/scenario/Application.js',
-    'src/scenario/Describe.js',
-    'src/scenario/Future.js',
-    'src/scenario/ObjectModel.js',
-    'src/scenario/Describe.js',
-    'src/scenario/Runner.js',
-    'src/scenario/SpecRunner.js',
-    'src/scenario/dsl.js',
-    'src/scenario/matchers.js',
-    'src/scenario/output/Html.js',
-    'src/scenario/output/Json.js',
-    'src/scenario/output/Xml.js',
-    'src/scenario/output/Object.js'
+    'src/ngScenario/Scenario.js',
+    'src/ngScenario/Application.js',
+    'src/ngScenario/Describe.js',
+    'src/ngScenario/Future.js',
+    'src/ngScenario/ObjectModel.js',
+    'src/ngScenario/Runner.js',
+    'src/ngScenario/SpecRunner.js',
+    'src/ngScenario/dsl.js',
+    'src/ngScenario/matchers.js',
+    'src/ngScenario/output/Html.js',
+    'src/ngScenario/output/Json.js',
+    'src/ngScenario/output/Xml.js',
+    'src/ngScenario/output/Object.js'
  ],

-  'jstd': [
-    'lib/jasmine/jasmine.js',
-    'lib/jasmine-jstd-adapter/JasmineAdapter.js',
+  'angularTest': [
+    'test/testabilityPatch.js',
+    'test/matchers.js',
+    'test/ngScenario/*.js',
+    'test/ngScenario/output/*.js',
+    'test/*.js',
+    'test/auto/*.js',
+    'test/bootstrap/*.js',
+    'test/ng/*.js',
+    'test/ng/directive/*.js',
+    'test/ng/filter/*.js',
+    'test/ngCookies/*.js',
+    'test/ngResource/*.js',
+    'test/ngSanitize/*.js',
+    'test/ngSanitize/directive/*.js',
+    'test/ngSanitize/filter/*.js',
+    'test/ngMock/*.js'
+  ],
+
+  'karma': [
    'lib/jquery/jquery.js',
    'test/jquery_remove.js',
    '@angularSrc',
+    'src/publishExternalApis.js',
+    '@angularSrcModules',
+    '@angularScenario',
+    '@angularTest',
    'example/personalLog/*.js',
-    'test/testabilityPatch.js',
-    'test/matchers.js',
-    'src/scenario/Scenario.js',
-    'src/scenario/output/*.js',
-    'src/jstd-scenario-adapter/*.js',
-    'src/scenario/*.js',
-    'src/angular-mocks.js',
-    'test/scenario/*.js',
-    'test/scenario/output/*.js',
-    'test/jstd-scenario-adapter/*.js',
-    'test/*.js',
-    'test/service/*.js',
-    'test/service/filter/*.js',
-    'test/directive/*.js',
    'example/personalLog/test/*.js'
  ],

-  'jstdExclude': [
+  'karmaExclude': [
    'test/jquery_alias.js',
    'src/angular-bootstrap.js',
-    'src/scenario/angular-bootstrap.js'
+    'src/ngScenario/angular-bootstrap.js'
  ],

-  'jstdScenario': [
+  'karmaScenario': [
    'build/angular-scenario.js',
-    'build/jstd-scenario-adapter-config.js',
-    'build/jstd-scenario-adapter.js',
    'build/docs/docs-scenario.js'
  ],

-  'jstdMocks': [
-    'lib/jasmine/jasmine.js',
-    'lib/jasmine-jstd-adapter/JasmineAdapter.js',
+  "karmaModules": [
    'build/angular.js',
-    'src/angular-mocks.js',
+    'src/ngMock/angular-mocks.js',
+    'src/ngCookies/cookies.js',
+    'src/ngResource/resource.js',
+    'src/ngSanitize/sanitize.js',
+    'src/ngSanitize/directive/ngBindHtml.js',
+    'src/ngSanitize/filter/linky.js',
    'test/matchers.js',
-    'test/angular-mocksSpec.js'
+    'test/ngMock/*.js',
+    'test/ngCookies/*.js',
+    'test/ngResource/*.js',
+    'test/ngSanitize/*.js',
+    'test/ngSanitize/directive/*.js',
+    'test/ngSanitize/filter/*.js'
  ],

-  'jstdPerf': [
-   'lib/jasmine/jasmine.js',
-   'lib/jasmine-jstd-adapter/JasmineAdapter.js',
-   'angularSrc',
-   'src/angular-mocks.js',
-   'perf/data/*.js',
-   'perf/testUtils.js',
-   'perf/*.js'
-  ],
-
-  'jstdPerfExclude': [
-    'src/angular-bootstrap.js',
-    'src/scenario/angular-bootstrap.js'
-  ],
-
-  'jstdJquery': [
-    'lib/jasmine/jasmine.js',
-    'lib/jasmine-jstd-adapter/JasmineAdapter.js',
+  'karmaJquery': [
    'lib/jquery/jquery.js',
    'test/jquery_alias.js',
    '@angularSrc',
+    'src/publishExternalApis.js',
+    '@angularSrcModules',
+    '@angularScenario',
+    '@angularTest',
    'example/personalLog/*.js',
-    'test/testabilityPatch.js',
-    'test/matchers.js',
-    'src/scenario/Scenario.js',
-    'src/scenario/output/*.js',
-    'src/jstd-scenario-adapter/*.js',
-    'src/scenario/*.js',
-    'src/angular-mocks.js',
-    'test/scenario/*.js',
-    'test/scenario/output/*.js',
-    'test/jstd-scenario-adapter/*.js',
-    'test/*.js',
-    'test/service/*.js',
-    'test/directive/*.js',
+
    'example/personalLog/test/*.js'
  ],

-  'jstdJqueryExclude': [
+  'karmaJqueryExclude': [
    'src/angular-bootstrap.js',
-    'src/scenario/angular-bootstrap.js',
+    'src/ngScenario/angular-bootstrap.js',
    'test/jquery_remove.js'
  ]
 };

-// Execute only in slim-jim
-if (typeof JASMINE_ADAPTER !== 'undefined') {
-  // SlimJim config
-  files = [JASMINE, JASMINE_ADAPTER];
-  angularFiles.jstd.forEach(function(pattern) {
-    // replace angular source
-    if (pattern === '@angularSrc') files = files.concat(angularFiles.angularSrc);
-    // ignore jstd and jasmine files
-    else if (!/jstd|jasmine/.test(pattern)) files.push(pattern);
-  });
+if (exports) {
+  exports.files = angularFiles;
+  exports.mergeFilesFor = function() {
+    var files = [];

-  exclude = angularFiles.jstdExclude;
+    Array.prototype.slice.call(arguments, 0).forEach(function(filegroup) {
+      angularFiles[filegroup].forEach(function(file) {
+        // replace @ref
+        var match = file.match(/^\@(.*)/);
+        if (match) {
+          files = files.concat(angularFiles[match[1]]);
+        } else {
+          files.push(file);
+        }
+      });
+    });

-  autoWatch = true;
-  autoWatchInterval = 1;
-  logLevel = LOG_INFO;
-  logColors = true;
+    return files;
+  };
 }
@@ -1,5 +0,0 @@
-bin
-cd angularjs.org/ng
-put angular-debug.js js/angular-debug.js
-put angular-minified.js js/angular-minified.js
-put angular-scenario.js js/angular-scenario.js
@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+// TODO(vojta): pre-commit hook for validating messages
+// TODO(vojta): report errors, currently Q silence everything which really sucks
+
+var child = require('child_process');
+var fs = require('fs');
+var util = require('util');
+var q = require('qq');
+
+var GIT_LOG_CMD = 'git log --grep="%s" -E --format=%s %s..HEAD';
+var GIT_TAG_CMD = 'git describe --tags --abbrev=0';
+
+var HEADER_TPL = '<a name="%s"></a>\n# %s (%s)\n\n';
+var LINK_ISSUE = '[#%s](https://github.com/angular/angular.js/issues/%s)';
+var LINK_COMMIT = '[%s](https://github.com/angular/angular.js/commit/%s)';
+
+var EMPTY_COMPONENT = '$$';
+var MAX_SUBJECT_LENGTH = 80;
+
+
+var warn = function() {
+  console.log('WARNING:', util.format.apply(null, arguments));
+};
+
+
+var parseRawCommit = function(raw) {
+  if (!raw) return null;
+
+  var lines = raw.split('\n');
+  var msg = {}, match;
+
+  msg.hash = lines.shift();
+  msg.subject = lines.shift();
+  msg.closes = [];
+  msg.breaks = [];
+
+  lines.forEach(function(line) {
+    match = line.match(/(?:Closes|Fixes)\s#(\d+)/);
+    if (match) msg.closes.push(parseInt(match[1]));
+  });
+
+  match = raw.match(/BREAKING CHANGE:([\s\S]*)/);
+  if (match) {
+    msg.breaking = match[1];
+  }
+
+
+  msg.body = lines.join('\n');
+  match = msg.subject.match(/^(.*)\((.*)\)\:\s(.*)$/);
+
+  if (!match || !match[1] || !match[3]) {
+    warn('Incorrect message: %s %s', msg.hash, msg.subject);
+    return null;
+  }
+
+  if (match[3].length > MAX_SUBJECT_LENGTH) {
+    warn('Too long subject: %s %s', msg.hash, msg.subject);
+    match[3] = match[3].substr(0, MAX_SUBJECT_LENGTH);
+  }
+
+  msg.type = match[1];
+  msg.component = match[2];
+  msg.subject = match[3];
+
+  return msg;
+};
+
+
+var linkToIssue = function(issue) {
+  return util.format(LINK_ISSUE, issue, issue);
+};
+
+
+var linkToCommit = function(hash) {
+  return util.format(LINK_COMMIT, hash.substr(0, 8), hash);
+};
+
+
+var currentDate = function() {
+  var now = new Date();
+  var pad = function(i) {
+    return ('0' + i).substr(-2);
+  };
+
+  return util.format('%d-%s-%s', now.getFullYear(), pad(now.getMonth() + 1), pad(now.getDate()));
+};
+
+
+var printSection = function(stream, title, section, printCommitLinks) {
+  printCommitLinks = printCommitLinks === undefined ? true : printCommitLinks;
+  var components = Object.getOwnPropertyNames(section).sort();
+
+  if (!components.length) return;
+
+  stream.write(util.format('\n## %s\n\n', title));
+
+  components.forEach(function(name) {
+    var prefix = '-';
+    var nested = section[name].length > 1;
+
+    if (name !== EMPTY_COMPONENT) {
+      if (nested) {
+        stream.write(util.format('- **%s:**\n', name));
+        prefix = '  -';
+      } else {
+        prefix = util.format('- **%s:**', name);
+      }
+    }
+
+    section[name].forEach(function(commit) {
+      if (printCommitLinks) {
+        stream.write(util.format('%s %s\n  (%s', prefix, commit.subject, linkToCommit(commit.hash)));
+        if (commit.closes.length) {
+          stream.write(',\n   ' + commit.closes.map(linkToIssue).join(', '));
+        }
+        stream.write(')\n');
+      } else {
+        stream.write(util.format('%s %s', prefix, commit.subject));
+      }
+    });
+  });
+
+  stream.write('\n');
+};
+
+
+var readGitLog = function(grep, from) {
+  var deferred = q.defer();
+
+  // TODO(vojta): if it's slow, use spawn and stream it instead
+  child.exec(util.format(GIT_LOG_CMD, grep, '%H%n%s%n%b%n==END==', from), function(code, stdout, stderr) {
+    var commits = [];
+
+    stdout.split('\n==END==\n').forEach(function(rawCommit) {
+      var commit = parseRawCommit(rawCommit);
+      if (commit) commits.push(commit);
+    });
+
+    deferred.resolve(commits);
+  });
+
+  return deferred.promise;
+};
+
+
+var writeChangelog = function(stream, commits, version) {
+  var sections = {
+    fix: {},
+    feat: {},
+    breaks: {}
+  };
+
+  sections.breaks[EMPTY_COMPONENT] = [];
+
+  commits.forEach(function(commit) {
+    var section = sections[commit.type];
+    var component = commit.component || EMPTY_COMPONENT;
+
+    if (section) {
+      section[component] = section[component] || [];
+      section[component].push(commit);
+    }
+
+    if (commit.breaking) {
+      sections.breaks[component] = sections.breaks[component] || [];
+      sections.breaks[component].push({
+        subject: util.format("due to %s,\n %s", linkToCommit(commit.hash), commit.breaking),
+        hash: commit.hash,
+        closes: []
+      });
+    };
+  });
+
+  stream.write(util.format(HEADER_TPL, version, version, currentDate()));
+  printSection(stream, 'Bug Fixes', sections.fix);
+  printSection(stream, 'Features', sections.feat);
+  printSection(stream, 'Breaking Changes', sections.breaks, false);
+}
+
+
+var getPreviousTag = function() {
+  var deferred = q.defer();
+  child.exec(GIT_TAG_CMD, function(code, stdout, stderr) {
+    if (code) deferred.reject('Cannot get the previous tag.');
+    else deferred.resolve(stdout.replace('\n', ''));
+  });
+  return deferred.promise;
+};
+
+
+var generate = function(version, file) {
+  getPreviousTag().then(function(tag) {
+    console.log('Reading git log since', tag);
+    readGitLog('^fix|^feat|BREAKING', tag).then(function(commits) {
+      console.log('Parsed', commits.length, 'commits');
+      console.log('Generating changelog to', file || 'stdout', '(', version, ')');
+      writeChangelog(file ? fs.createWriteStream(file) : process.stdout, commits, version);
+    });
+  });
+};
+
+
+// publish for testing
+exports.parseRawCommit = parseRawCommit;
+
+// hacky start if not run by jasmine :-D
+if (process.argv.join('').indexOf('jasmine-node') === -1) {
+  generate(process.argv[2], process.argv[3]);
+}
@@ -0,0 +1,43 @@
+describe('changelog.js', function() {
+  var ch = require('./changelog');
+
+  describe('parseRawCommit', function() {
+    it('should parse raw commit', function() {
+      var msg = ch.parseRawCommit(
+          '9b1aff905b638aa274a5fc8f88662df446d374bd\n' +
+          'feat(scope): broadcast $destroy event on scope destruction\n' +
+          'perf testing shows that in chrome this change adds 5-15% overhead\n' +
+          'when destroying 10k nested scopes where each scope has a $destroy listener\n');
+
+      expect(msg.type).toBe('feat');
+      expect(msg.hash).toBe('9b1aff905b638aa274a5fc8f88662df446d374bd');
+      expect(msg.subject).toBe('broadcast $destroy event on scope destruction');
+      expect(msg.body).toBe('perf testing shows that in chrome this change adds 5-15% overhead\n' +
+          'when destroying 10k nested scopes where each scope has a $destroy listener\n')
+      expect(msg.component).toBe('scope');
+    });
+
+
+    it('should parse closed issues', function() {
+      var msg = ch.parseRawCommit(
+          '13f31602f396bc269076ab4d389cfd8ca94b20ba\n' +
+          'feat(ng-list): Allow custom separator\n' +
+          'bla bla bla\n\n' +
+          'Closes #123\nCloses #25\n');
+
+      expect(msg.closes).toEqual([123, 25]);
+    });
+
+
+    it('should parse breaking changes', function() {
+      var msg = ch.parseRawCommit(
+          '13f31602f396bc269076ab4d389cfd8ca94b20ba\n' +
+          'feat(ng-list): Allow custom separator\n' +
+          'bla bla bla\n\n' +
+          'BREAKING CHANGE: first breaking change\nsomething else\n' +
+          'another line with more info\n');
+
+      expect(msg.breaking).toEqual(' first breaking change\nsomething else\nanother line with more info\n');
+    });
+  });
+});
@@ -0,0 +1,80 @@
+<a name="v1.0.0rc3"></a>
+# v1.0.0rc3 (2012-03-27)
+
+
+## Bug Fixes
+
+- **$compile:**
+  - create new (isolate) scopes for directives on root elements ([5390fb37](https://github.com/angular/angular.js/commit/5390fb37d2c01937922613fc57df4986af521787), closes [#817](https://github.com/angular/angular.js/issues/817))
+  - don't touch static element attributes ([9cb2195e](https://github.com/angular/angular.js/commit/9cb2195e61a78e99020ec19d687a221ca88b5900))
+  - Merge interpolated css class when replacing an element ([f49eaf8b](https://github.com/angular/angular.js/commit/f49eaf8bf2df5f4e0e82d6c89e849a4f82c8d414))
+- **$http:**
+  - don't send Content-Type header when no data ([1a5bebd9](https://github.com/angular/angular.js/commit/1a5bebd927ecd22f9c34617642fdf58fe3f62efb), closes [#749](https://github.com/angular/angular.js/issues/749))
+- **$log:**
+  - avoid console.log.apply calls in IE ([15213ec2](https://github.com/angular/angular.js/commit/15213ec212769837cb2b7e781ffc5bfd598d27ca), closes [#805](https://github.com/angular/angular.js/issues/805))
+- **$resource:**
+  - support escaping of ':' in resource url ([6d6f8753](https://github.com/angular/angular.js/commit/6d6f875345e01f2c6c63ef95164f6f39e923da15))
+- **compiler:**
+  - allow transclusion of root elements ([9918b748](https://github.com/angular/angular.js/commit/9918b748be01266eb10db39d51b4d3098d54ab66))
+- **e2e runner:**
+  - fix typo that caused errors on IE8 ([ee5a5352](https://github.com/angular/angular.js/commit/ee5a5352fd4b94cedee6ef20d4bf2d43ce77e00b), closes [#806](https://github.com/angular/angular.js/issues/806))
+- **forEach:**
+  - should ignore prototypically inherited properties ([8d7e6948](https://github.com/angular/angular.js/commit/8d7e6948496ff26ef1da8854ba02fcb8eebfed61), closes [#813](https://github.com/angular/angular.js/issues/813))
+- **forms:**
+  - Remove double registering of form ([1faafa31](https://github.com/angular/angular.js/commit/1faafa31582c4e9413f48dc7d12f5b681f9fe9fd))
+  - Set ng-valid/ng-invalid correctly ([08bfea18](https://github.com/angular/angular.js/commit/08bfea183a850b29da270eac47f80b598cbe600f))
+- **init:**
+  - use jQuery#ready for init if available ([cb2ad9ab](https://github.com/angular/angular.js/commit/cb2ad9abf24e6f855cc749efe3155bd7987ece9d), closes [#818](https://github.com/angular/angular.js/issues/818))
+- **json:**
+  - added support for iso8061 timezone ([5ac14f63](https://github.com/angular/angular.js/commit/5ac14f633a69f49973b5512780c6ec7752405967))
+- **matchers.toHaveClass:**
+  - Correct reference to angular.mock.dump ([f701ce08](https://github.com/angular/angular.js/commit/f701ce08f9d63be05fc3b92f57ad473e1e749b2d))
+- **ng-switch:**
+  - properly destroy child scopes ([2315d9b3](https://github.com/angular/angular.js/commit/2315d9b3610994b36c44e4a97fb1427d59471ce8))
+- **ngDocSpec:**
+  - fix broken tests ([53b6f522](https://github.com/angular/angular.js/commit/53b6f522a56eea314cbd084816e08f24b2c7879f))
+- **ngForm:**
+  - alias name||ngForm ([823adb23](https://github.com/angular/angular.js/commit/823adb231995e917bc060bfa49453e2a96bac2b6))
+- **ngRepeat:**
+  - correct variable reference in error message ([935c1018](https://github.com/angular/angular.js/commit/935c1018da05dbf3124b2dd33619c4a3c82d7a2a))
+- **ngView:**
+  - controller not published ([21e74c2d](https://github.com/angular/angular.js/commit/21e74c2d2e8e985b23711785287feb59965cbd90))
+- **q:**
+  - resolve all of nothing to nothing ([ac75079e](https://github.com/angular/angular.js/commit/ac75079e2113949d5d64adbcf23d56f3cf295d41))
+- **select:**
+  - multiselect failes to update view on selection insert ([6ecac8e7](https://github.com/angular/angular.js/commit/6ecac8e71a84792a434d21db2c245b3648c55f18))
+
+
+## Features
+
+- **$compile:**
+  - do not interpolate boolean attributes, rather evaluate them ([a08cbc02](https://github.com/angular/angular.js/commit/a08cbc02e78e789a66e9af771c410e8ad1646e25))
+- **$controller:**
+  - support controller registration via $controllerProvider ([d54dfecb](https://github.com/angular/angular.js/commit/d54dfecb00fba41455536c5ddd55310592fdaf84))
+- **$route:**
+  - when matching consider trailing slash as optional ([a4fe51da](https://github.com/angular/angular.js/commit/a4fe51da3ba0dc297ecd389e230d6664f250c9a6), closes [#784](https://github.com/angular/angular.js/issues/784))
+- **assertArgFn:**
+  - should support array annotated fns ([4b8d9260](https://github.com/angular/angular.js/commit/4b8d926062eb4d4483555bdbdec4656f585ab40b))
+- **http:**
+  - added params parameter ([73c85930](https://github.com/angular/angular.js/commit/73c8593077155a9f2e8ef42efd4c497eba0bef4f))
+- **injector:**
+  - infer _foo_ as foo ([f13dd339](https://github.com/angular/angular.js/commit/f13dd3393dfb7a33565c9360342c193bc0bddcb6))
+- **input.radio:**
+  - Allow value attribute to be interpolated ([ade6c452](https://github.com/angular/angular.js/commit/ade6c452753145c84884d17027a7865bf4b34b0c))
+- **jqLite:**
+  - make injector() and scope() work with the document object ([5fdab52d](https://github.com/angular/angular.js/commit/5fdab52dd7c269f99839f4fa6b5854d9548269fa))
+  - add .controller() method ([6c5a05ad](https://github.com/angular/angular.js/commit/6c5a05ad49a1e083570c3dfe331403398f899dbe))
+- **ngValue:**
+  - allow radio inputs to have non string values ([09e175f0](https://github.com/angular/angular.js/commit/09e175f02cca0f4a295fd0c9b980cd8f432e722b), closes [#816](https://github.com/angular/angular.js/issues/816))
+- **scope:**
+  - broadcast $destroy event on scope destruction ([9b1aff90](https://github.com/angular/angular.js/commit/9b1aff905b638aa274a5fc8f88662df446d374bd))
+- **scope.$eval:**
+  - Allow passing locals to the expression ([192ff61f](https://github.com/angular/angular.js/commit/192ff61f5d61899e667c6dbce4d3e6e399429d8b))
+
+
+## Breaking Changes
+
+- boolean attrs are evaluated rather than interpolated ([a08cbc02](https://github.com/angular/angular.js/commit/a08cbc02e78e789a66e9af771c410e8ad1646e25))
+- ng-bind-attr directive removed ([55027132](https://github.com/angular/angular.js/commit/55027132f3d57e5dcf94683e6e6bd7b0aae0087d))
+- any app that depends on this service and its fallback to Modernizr, please ([aaedefb9](https://github.com/angular/angular.js/commit/aaedefb92e6bec6626e173e5155072c91471596a))
+
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+grunt minify
+gzip -c < build/angular.min.js > build/angular.min.js.gzip
+ls -l build/angular.min.*
@@ -0,0 +1,14 @@
+This file contains externs for use with the Closure compiler (aka JSCompiler).
+Passing these files to the --externs parameter of a compiler pass allows using
+type annotations for AngularJS objects. For example, Angular's $scope objects
+can be annotated as:
+  /** @type {angular.Scope} */ var scope = $scope;
+
+This allows JSCompiler to type check accesses to scope, give warnings about
+missing methods or incorrect arguments, and also prevents renaming of property
+accesses with advanced compilation.
+
+The externs are incomplete and maintained on an as-needed basis, but strive to
+be correct. Externs for individual modules should be added in separate files.
+
+See https://developers.google.com/closure/compiler/
@@ -2,7 +2,7 @@

 [ng\:cloak], [ng-cloak], [data-ng-cloak], [x-ng-cloak],
 .ng-cloak, .x-ng-cloak {
-  display: none;
+  display: none !important;
 }

 ng\:form {
@@ -2,62 +2,6 @@
@name API Reference
@description

-## Angular Compiler API
-
-* {@link angular.module.ng.$compileProvider.directive Directives} - Angular DOM element attributes
-* {@link angular.module.ng.$filter Filters} - Angular output filters
-* {@link angular.module.ng.$compile $compile} - Template compiler
-
-## Angular Scope API
-
-* {@link angular.module.ng.$rootScope.Scope Scope Object} - Angular scope object
-
-
-## Angular Services & Dependency Injection API
-
-* {@link angular.module.ng Angular Services}
-* {@link angular.injector angular.injector() }
-
-
-## Angular Testing API
-
-* {@link angular.module.ngMock Testing Mocks API} - Mock objects for testing
-* {@link guide/dev_guide.e2e-testing Angular Scenario Runner} - Automated scenario testing
-documentation
-
-
-## Angular Utility Functions
-
-### HTML & DOM Manipulation
-
-* {@link angular.element angular.element()}
-
-### Misc
-
-* {@link angular.bind angular.bind() }
-* {@link angular.extend angular.extend() }
-* {@link angular.forEach angular.forEach() }
-* {@link angular.identity angular.identity() }
-* {@link angular.noop angular.noop() }
-
-
-## Type Identification
-
-* {@link angular.isArray angular.isArray() }
-* {@link angular.isDate angular.isDate() }
-* {@link angular.isDefined angular.isDefined() }
-* {@link angular.isFunction angular.isFunction() }
-* {@link angular.isNumber angular.isNumber() }
-* {@link angular.isObject angular.isObject() }
-* {@link angular.isString angular.isString() }
-* {@link angular.isUndefined angular.isUndefined() }
-
-## Strings
-
-* {@link angular.lowercase angular.lowercase() }
-* {@link angular.uppercase angular.uppercase() }
-
-### JSON
-
-* {@link angular.fromJson angular.fromJson() }
-* {@link angular.toJson angular.toJson() }
+Use the API Reference documentation when you need more information about a specific feature. Check out
+{@link guide/ Developer Guide} for AngularJS concepts. If you are new to AngularJS we recommend the
+{@link tutorial/ Tutorial}.
@@ -1,5 +1,5 @@
@ngdoc overview
-@name angular.module.ng
+@name ng
@description

 The `ng` is an angular module which contains all of the core angular services.
@@ -85,8 +85,8 @@ detection, and preventing invalid form submission.
         <input type="text" ng-model="contact.value" required/>
          [ <a href="" ng-click="removeContact(contact)">X</a> ]
       </div>
-     <button ng-click="cancel()" ng-disabled="{{isCancelDisabled()}}">Cancel</button>
-     <button ng-click="save()" ng-disabled="{{isSaveDisabled()}}">Save</button>
+     <button ng-click="cancel()" ng-disabled="isCancelDisabled()">Cancel</button>
+     <button ng-click="save()" ng-disabled="isSaveDisabled()">Save</button>
   </form>

   <hr/>
@@ -3,7 +3,7 @@
@description

 External resources are URLs that provide JSON data, which are then rendered with the help of
-templates. angular has a resource factory that can be used to give names to the URLs and then
+templates. Angular has a resource factory that can be used to give names to the URLs and then
 attach behavior to them. For example you can use the
 {@link http://code.google.com/apis/buzz/v1/getting_started.html#background-operations| Google Buzz
 API}
@@ -12,22 +12,22 @@ to retrieve Buzz activity and comments.
 <doc:example>
 <doc:source>
    <script>
-    BuzzController.$inject = ['$resource'];
-    function BuzzController($resource) {
-     this.userId = 'googlebuzz';
-     this.Activity = $resource(
+    BuzzController.$inject = ['$scope', '$resource'];
+    function BuzzController($scope, $resource) {
+     $scope.userId = 'googlebuzz';
+     $scope.Activity = $resource(
      'https://www.googleapis.com/buzz/v1/activities/:userId/:visibility/:activityId/:comments',
      {alt: 'json', callback: 'JSON_CALLBACK'},
      { get:     {method: 'JSONP', params: {visibility: '@self'}},
        replies: {method: 'JSONP', params: {visibility: '@self', comments: '@comments'}}
      });
-    }
-    BuzzController.prototype = {
-     fetch: function() {
-      this.activities = this.Activity.get({userId:this.userId});
-     },
-     expandReplies: function(activity) {
-      activity.replies = this.Activity.replies({userId: this.userId, activityId: activity.id});
+
+     $scope.fetch = function() {
+      $scope.activities = $scope.Activity.get({userId:this.userId});
+     }
+
+     $scope.expandReplies = function(activity) {
+      activity.replies = $scope.Activity.replies({userId: this.userId, activityId: activity.id});
     }
    };
    </script>
@@ -5,7 +5,7 @@
 Deep linking allows you to encode the state of the application in the URL so that it can be
 bookmarked and the application can be restored from the URL to the same state.

-While <angular/> does not force you to deal with bookmarks in any particular way, it has services
+While Angular does not force you to deal with bookmarks in any particular way, it has services
 which make the common case described here very easy to implement.

 # Assumptions
@@ -30,83 +30,122 @@ In this example we have a simple app which consist of two screens:
 * Welcome: url `welcome` Show the user contact information.
 * Settings: url `settings` Show an edit screen for user contact information.

+<example module="deepLinking" deps="angular-sanitize.js">
+ <file name="script.js">
+   angular.module('deepLinking', ['ngSanitize'])
+     .config(function($routeProvider) {
+        $routeProvider.
+          when("/welcome",  {templateUrl:'welcome.html',  controller:WelcomeCntl}).
+          when("/settings", {templateUrl:'settings.html', controller:SettingsCntl});
+     });

-The two partials are defined in the following URLs:
+   AppCntl.$inject = ['$scope', '$route']
+   function AppCntl($scope, $route) {
+    $scope.$route = $route;

-* <a href="./examples/settings.html" ng-ext-link>./examples/settings.html</a>
-* <a href="./examples/welcome.html" ng-ext-link>./examples/welcome.html</a>
+    // initialize the model to something useful
+    $scope.person = {
+     name:'anonymous',
+     contacts:[{type:'email', url:'anonymous@example.com'}]
+    };
+   }

-<doc:example module="deepLinking">
- <doc:source jsfiddle="false">
-    <script>
-     angular.module('deepLinking', [])
-       .config(function($routeProvider) {
-          $routeProvider.when("/welcome",  {template:'./examples/welcome.html',  controller:WelcomeCntl});
-          $routeProvider.when("/settings", {template:'./examples/settings.html', controller:SettingsCntl});
-       });
+   function WelcomeCntl($scope) {
+    $scope.greet = function() {
+     alert("Hello " + $scope.person.name);
+    };
+   }

-     AppCntl.$inject = ['$scope', '$route']
-     function AppCntl($scope, $route) {
-      // initialize the model to something useful
-      $scope.person = {
-       name:'anonymous',
-       contacts:[{type:'email', url:'anonymous@example.com'}]
-      };
-     }
+   function SettingsCntl($scope, $location) {
+    $scope.cancel = function() {
+     $scope.form = angular.copy($scope.person);
+    };

-     function WelcomeCntl($scope) {
-      $scope.greet = function() {
-       alert("Hello " + $scope.person.name);
-      };
-     }
+    $scope.save = function() {
+     angular.copy($scope.form, $scope.person);
+     $location.path('/welcome');
+    };

-     function SettingsCntl($scope, $location) {
-      $scope.cancel = function() {
-       $scope.form = angular.copy($scope.person);
-      };
+    $scope.cancel();
+   }
+ </file>
+ <file name="style.css">
+   [ng-view] {
+     border: 1px solid blue;
+     margin: 0;
+     padding:1em;
+   }

-      $scope.save = function() {
-       angular.copy($scope.form, $scope.person);
-       $location.path('/welcome');
-      };
-
-      $scope.cancel();
-     }
-    </script>
+   .partial-info {
+      background-color: blue;
+      color: white;
+      padding: 3px;
+    }
+ </file>
+ <file name="index.html">
    <div ng-controller="AppCntl">
      <h1>Your App Chrome</h1>
      [ <a href="welcome">Welcome</a> | <a href="settings">Settings</a> ]
      <hr/>
-      <span style="background-color: blue; color: white; padding: 3px;">
+      <span class="partial-info">
        Partial: {{$route.current.template}}
      </span>
-      <ng:view style="border: 1px solid blue; margin: 0; display:block; padding:1em;"></ng:view>
+      <div ng-view></div>
      <small>Your app footer </small>
    </div>
- </doc:source>
- <doc:scenario>
+ </file>
+ <file name="settings.html">
+   <label>Name:</label>
+   <input type="text" ng:model="form.name" required>
+
+   <div ng:repeat="contact in form.contacts">
+     <select ng:model="contact.type">
+       <option>url</option>
+       <option>email</option>
+       <option>phone</option>
+     </select>
+     <input type="text" ng:model="contact.url">
+     [ <a href="" ng:click="form.contacts.$remove(contact)">X</a> ]
+   </div>
+   <div>
+     [ <a href="" ng:click="form.contacts.$add()">add</a> ]
+   </div>
+
+   <button ng:click="cancel()">Cancel</button>
+   <button ng:click="save()">Save</button>
+ </file>
+ <file name="welcome.html">
+   Hello {{person.name}},
+   <div>
+     Your contact information:
+     <div ng:repeat="contact in person.contacts">{{contact.type}}:
+       <span ng-bind-html="contact.url|linky"></span>
+     </div>
+   </div>
+ </file>
+ <file name="scenario.js">
   it('should navigate to URL', function() {
-    element('a:contains(Welcome)').click();
-    expect(element('ng\\:view').text()).toMatch(/Hello anonymous/);
-    element('a:contains(Settings)').click();
-    input('form.name').enter('yourname');
-    element(':button:contains(Save)').click();
-    element('a:contains(Welcome)').click();
-    expect(element('ng\\:view').text()).toMatch(/Hello yourname/);
+     element('a:contains(Welcome)').click();
+     expect(element('[ng-view]').text()).toMatch(/Hello anonymous/);
+     element('a:contains(Settings)').click();
+     input('form.name').enter('yourname');
+     element(':button:contains(Save)').click();
+     element('a:contains(Welcome)').click();
+     expect(element('[ng-view]').text()).toMatch(/Hello yourname/);
   });
- </doc:scenario>
-</doc:example>
+ </file>
+</example>



 # Things to notice

 * Routes are defined in the `AppCntl` class. The initialization of the controller causes the
-  initialization of the {@link api/angular.module.ng.$route $route} service with the proper URL
+  initialization of the {@link api/ng.$route $route} service with the proper URL
  routes.
-* The  {@link api/angular.module.ng.$route $route} service then watches the URL and instantiates the
+* The  {@link api/ng.$route $route} service then watches the URL and instantiates the
  appropriate controller when the URL changes.
-* The  {@link api/angular.module.ng.$compileProvider.directive.ng-view ng-view} widget loads the
+* The  {@link api/ng.directive:ngView ngView} widget loads the
  view when the URL changes. It also sets the view scope to the newly instantiated controller.
 * Changing the URL is sufficient to change the controller and view. It makes no difference whether
  the URL is changed programatically or by the user.
@@ -2,7 +2,7 @@
@name Cookbook: Form
@description

-A web application's main purpose is to present and gather data. For this reason angular strives
+A web application's main purpose is to present and gather data. For this reason Angular strives
 to make both of these operations trivial. This example shows off how you can build a simple form to
 allow a user to enter data.

@@ -11,7 +11,7 @@ allow a user to enter data.
 <doc:source>
  <script>
    function FormController($scope) {
-      $scope.user = {
+      var user = $scope.user = {
        name: 'John Smith',
        address:{line1: '123 Main St.', city:'Anytown', state:'AA', zip:'12345'},
        contacts:[{type:'phone', value:'1(234) 555-1212'}]
@@ -20,12 +20,12 @@ allow a user to enter data.
      $scope.zip = /^\d\d\d\d\d$/;

      $scope.addContact = function() {
-         $scope.user.contacts.push({type:'', value:''});
+         user.contacts.push({type:'email', value:''});
      };

      $scope.removeContact = function(contact) {
-        for (var i = 0, ii = this.user.contacts.length; i < ii; i++) {
-          if (contact === this.user.contacts[i]) {
+        for (var i = 0, ii = user.contacts.length; i < ii; i++) {
+          if (contact === user.contacts[i]) {
            $scope.user.contacts.splice(i, 1);
          }
        }
@@ -34,16 +34,16 @@ allow a user to enter data.
  </script>
  <div ng-controller="FormController" class="example">

-    <label>Name:</label><br/>
-    <input type="text" ng-model="user.name" required/> <br/><br/>
+    <label>Name:</label><br>
+    <input type="text" ng-model="user.name" required/> <br><br>

-    <label>Address:</label><br/>
-    <input type="text" ng-model="user.address.line1" size="33" required> <br/>
+    <label>Address:</label><br>
+    <input type="text" ng-model="user.address.line1" size="33" required> <br>
    <input type="text" ng-model="user.address.city" size="12" required>,
-    <input type="text" ng-model="user.address.state" size="2"
-           ng-pattern="state" required>
+    <input type="text" ng-model="user.address.state"
+           ng-pattern="state" size="2" required>
    <input type="text" ng-model="user.address.zip" size="5"
-           ng-pattern="zip" required><br/><br/>
+           ng-pattern="zip" required><br><br>

    <label>Phone:</label>
    [ <a href="" ng-click="addContact()">add</a> ]
@@ -54,12 +54,12 @@ allow a user to enter data.
        <option>pager</option>
        <option>IM</option>
      </select>
-      <input type="text" ng-model="contact.value" required/>
+      <input type="text" ng-model="contact.value" required>
       [ <a href="" ng-click="removeContact(contact)">X</a> ]
    </div>
    <hr/>
    Debug View:
-    <pre>user={{user}}</pre>
+    <pre>user={{user | json}}</pre>
  </div>

 </doc:source>
@@ -102,14 +102,13 @@ allow a user to enter data.

 # Things to notice

-* The user data model is initialized {@link api/angular.module.ng.$compileProvider.directive.ng-controller controller} and is
-  available in the {@link api/angular.module.ng.$rootScope.Scope scope} with the initial data.
+* The user data model is initialized {@link api/ng.directive:ngController controller} and is
+  available in the {@link api/ng.$rootScope.Scope scope} with the initial data.
 * For debugging purposes we have included a debug view of the model to better understand what
  is going on.
-* The {@link api/angular.module.ng.$compileProvider.directive.input input directives} simply refer
+* The {@link api/ng.directive:input input directives} simply refer
  to the model and are data-bound.
-* The inputs {@link guide/dev_guide.forms validate}. (Try leaving them blank or entering non digits
-  in the zip field)
+* The inputs validate. (Try leaving them blank or entering non digits in the zip field)
 * In your application you can simply read from or write to the model and the form will be updated.
 * By clicking the 'add' link you are adding new items into the `user.contacts` array which are then
  reflected in the view.
@@ -10,9 +10,9 @@
    }
  </script>
  <div ng-controller="HelloCntl">
-    Your name: <input type="text" ng-model="name" value="World"/>
+    Your name: <input type="text" ng-model="name"/>
    <hr/>
-    Hello {{name}}!
+    Hello {{name || "World"}}!
  </div>
 </doc:source>
 <doc:scenario>
@@ -28,11 +28,11 @@

 Take a look through the source and note:

-* The script tag that {@link guide/dev_guide.bootstrap bootstraps} the angular environment.
-* The text {@link api/angular.module.ng.$compileProvider.directive.input input widget} which is
+* The script tag that {@link guide/bootstrap bootstraps} the Angular environment.
+* The text {@link api/ng.directive:input input form control} which is
  bound to the greeting name text.
-* No need for listener registration and event firing on change events.
-* The implicit presence of the `name` variable which is in the root {@link api/angular.module.ng.$rootScope.Scope scope}.
+* There is no need for listener registration and event firing on change events.
+* The implicit presence of the `name` variable which is in the root {@link api/ng.$rootScope.Scope scope}.
 * The double curly brace `{{markup}}`, which binds the name variable to the greeting text.
 * The concept of {@link guide/dev_guide.templates.databinding data binding}, which reflects any
 changes to the
@@ -2,7 +2,7 @@
@name Cookbook
@description

-Welcome to the angular cookbook. Here we will show you typical uses of angular by example.
+Welcome to the Angular cookbook. Here we will show you typical uses of Angular by example.


 # Hello World
@@ -44,8 +44,8 @@ allowing you to send links to specific screens in your app.

 # Services

-{@link api/angular.module.ng Services}: Services are long lived objects in your applications that are
-available across controllers. A collection of useful services are pre-bundled with angular but you
+{@link api/ng Services}: Services are long lived objects in your applications that are
+available across controllers. A collection of useful services are pre-bundled with Angular but you
 will likely add your own. Services are initialized using dependency injection, which resolves the
 order of initialization. This safeguards you from the perils of global state (a common way to
 implement long lived objects).
@@ -55,4 +55,4 @@ implement long lived objects).

 {@link buzz Resources}: Web applications must be able to communicate with the external
 services to get and update data. Resources are the abstractions of external URLs which are
-specially tailored to angular data binding.
+specially tailored to Angular data binding.
@@ -2,13 +2,14 @@
@name Cookbook: MVC
@description

-MVC allows for a clean an testable separation between the behavior (controller) and the view
+MVC allows for a clean and testable separation between the behavior (controller) and the view
 (HTML template). A Controller is just a JavaScript class which is grafted onto the scope of the
 view. This makes it very easy for the controller and the view to share the model.

-The model is simply the controller's this. This makes it very easy to test the controller in
-isolation since one can simply instantiate the controller and test without a view, because there is
-no connection between the controller and the view.
+The model is a set of objects and primitives that are referenced from the Scope ($scope) object.
+This makes it very easy to test the controller in isolation since one can simply instantiate the
+controller and test without a view, because there is no connection between the controller and the
+view.


 <doc:example>
@@ -114,7 +115,7 @@ no connection between the controller and the view.
 # Things to notice

 * The controller is defined in JavaScript and has no reference to the rendering logic.
-* The controller is instantiated by <angular/> and injected into the view.
+* The controller is instantiated by Angular and injected into the view.
 * The controller can be instantiated in isolation (without a view) and the code will still execute.
 This makes it very testable.
 * The HTML view is a projection of the model. In the above example, the model is stored in the
@@ -124,4 +125,4 @@ board variable.
 * The view can call any controller function.
 * In this example, the `setUrl()` and `readUrl()` functions copy the game state to/from the URL's
 hash so the browser's back button will undo game steps. See deep-linking. This example calls {@link
-api/angular.module.ng.$rootScope.Scope#$watch $watch()} to set up a listener that invokes `readUrl()` when needed.
+api/ng.$rootScope.Scope#$watch $watch()} to set up a listener that invokes `readUrl()` when needed.
@@ -0,0 +1,114 @@
+@ngdoc overview
+@name Developer Guide: Bootstrap
+@description
+
+# Overview
+
+This page explains the Angular initialization process and how you can manually initialize Angular
+if necessary.
+
+## Angular `<script>` Tag
+
+This example shows the recommended path for integrating Angular with what we call automatic
+initialization.
+
+
+<pre>
+<!doctype html>
+<html xmlns:ng="http://angularjs.org" ng-app>
+  <body>
+    ...
+    <script src="angular.js">
+  </body>
+</html>
+</pre>
+
+  * Place the `script` tag at the bottom of the page. Placing script tags at the end of the page
+    improves app load time because the HTML loading is not blocked by loading of the `angular.js`
+    script. You can get the latest bits from {@link http://code.angularjs.org}. Please don't link
+    your production code to this URL, as it will expose a security hole on your site. For
+    experimental development linking to our site is fine.
+    * Choose: `angular-[version].js` for a human-readable file, suitable for development and
+      debugging.
+    * Choose: `angular-[version].min.js` for a compressed and obfuscated file, suitable for use in
+      production.
+  * Place `ng-app` to the root of your application, typically on the `<html>` tag if you want
+    angular to auto-bootstrap your application.
+
+        <html ng-app>
+
+  * If IE7 support is required add `id="ng-app"`
+
+        <html ng-app id="ng-app">
+
+  * If you choose to use the old style directive syntax `ng:` then include xml-namespace in `html`
+    to make IE happy. (This is here for historical reasons, and we no longer recommend use of
+    `ng:`.)
+
+        <html xmlns:ng="http://angularjs.org">
+
+
+
+## Automatic Initialization
+
+Angular initializes automatically upon `DOMContentLoaded` event, at which point Angular looks for
+the {@link api/ng.directive:ngApp `ng-app`} directive which
+designates your application root. If the {@link
+api/ng.directive:ngApp `ng-app`} directive is found then Angular
+will:
+
+  * load the {@link guide/module module} associated with the directive.
+  * create the application {@link api/AUTO.$injector injector}
+  * compile the DOM treating the {@link api/ng.directive:ngApp
+    `ng-app`} directive as the root of the compilation. This allows you to tell it to treat only a
+    portion of the DOM as an Angular application.
+
+
+<pre>
+<!doctype html>
+<html ng-app="optionalModuleName">
+  <body>
+    I can add: {{ 1+2 }}.
+    <script src="angular.js"></script>
+  </body>
+</html>
+</pre>
+
+
+
+## Manual Initialization
+
+
+If you need to have more control over the initialization process, you can use a manual
+bootstrapping method instead. Examples of when you'd need to do this include using script loaders
+or the need to perform an operation before Angular compiles a page.
+
+Here is an example of manually initializing Angular:
+
+<pre>
+<!doctype html>
+<html xmlns:ng="http://angularjs.org">
+  <body>
+    Hello {{'World'}}!
+    <script src="http://code.angularjs.org/angular.js"></script>
+    <script>
+       angular.element(document).ready(function() {
+         angular.module('myApp', []);
+         angular.bootstrap(document, ['myApp']);
+       });
+    </script>
+  </body>
+</html>
+</pre>
+
+Note that we have provided the name of our application module to be loaded into the injector as the second
+parameter of the {@link api/angular.bootstrap} function. Notice that `angular.bootstrap` will not create modules 
+on the fly. You must create any custom {@link guide/module modules} before you pass them as a parameter. 
+
+This is the sequence that your code should follow:
+
+  1. After the page and all of the code is loaded, find the root element of your AngularJS
+  application, which is typically the root of the document.
+
+  2. Call {@link api/angular.bootstrap} to {@link compiler compile} the element into an
+  executable, bi-directionally bound application.
@@ -0,0 +1,142 @@
+@ngdoc overview
+@name Developer Guide: HTML Compiler
+@description
+
+# Overview
+
+Angular's {@link api/ng.$compile HTML compiler} allows the developer to teach the
+browser new HTML syntax. The compiler allows you to attach behavior to any HTML element or attribute
+and even create new HTML elements or attributes with custom behavior. Angular calls these behavior
+extensions {@link api/ng.$compileProvider#directive directives}.
+
+HTML has a lot of constructs for formatting the HTML for static documents in a declarative fashion.
+For example if something needs to be centered, there is no need to provide instructions to the
+browser how the window size needs to be divided in half so that the center is found, and that this
+center needs to be aligned with the text's center. Simply add an `align="center"` attribute to any
+element to achieve the desired behavior. Such is the power of declarative language.
+
+But the declarative language is also limited, since it does not allow you to teach the browser new
+syntax. For example there is no easy way to get the browser to align the text at 1/3 the position
+instead of 1/2. What is needed is a way to teach the browser new HTML syntax.
+
+Angular comes pre-bundled with common directives which are useful for building any app. We also
+expect that you will create directives that are specific to your app. These extensions become a
+Domain Specific Language for building your application.
+
+All of this compilation takes place in the web browser; no server side or pre-compilation step is
+involved.
+
+
+# Compiler
+
+Compiler is an angular service which traverses the DOM looking for attributes. The compilation
+process happens in two phases.
+
+  1. **Compile:** traverse the DOM and collect all of the directives. The result is a linking
+  function.
+
+  2. **Link:** combine the directives with a scope and produce a live view. Any changes in the
+  scope model are reflected in the view, and any user interactions with the view are reflected
+  in the scope model. This makes the scope model the single source of truth.
+
+Some directives such as {@link api/ng.directive:ngRepeat `ng-repeat`} clone DOM elements once
+for each item in a collection. Having a compile and link phase improves performance since the
+cloned template only needs to be compiled once, and then linked once for each clone instance.
+
+
+# Directive
+
+A directive is a behavior which should be triggered when specific HTML constructs are encountered
+during the compilation process. The directives can be placed in element names, attributes, class
+names, as well as comments. Here are some equivalent examples of invoking the {@link
+api/ng.directive:ngBind `ng-bind`} directive.
+
+<pre>
+  <span ng-bind="exp"></span>
+  <span class="ng-bind: exp;"></span>
+  <ng-bind></ng-bind>
+  <!-- directive: ng-bind exp -->
+</pre>
+
+A directive is just a function which executes when the compiler encounters it in the DOM. See {@link
+api/ng.$compileProvider#directive directive API} for in-depth documentation on how
+to write directives.
+
+Here is a directive which makes any element draggable. Notice the `draggable` attribute on the
+`<span>` element.
+
+<example module="drag">
+  <file name="script.js">
+    angular.module('drag', []).
+      directive('draggable', function($document) {
+        return function(scope, element, attr) {
+          var startX = 0, startY = 0, x = 0, y = 0;
+          element.css({
+           position: 'relative',
+           border: '1px solid red',
+           backgroundColor: 'lightgrey',
+           cursor: 'pointer'
+          });
+          element.bind('mousedown', function(event) {
+            // Prevent default dragging of selected content
+            event.preventDefault();
+            startX = event.screenX - x;
+            startY = event.screenY - y;
+            $document.bind('mousemove', mousemove);
+            $document.bind('mouseup', mouseup);
+          });
+
+          function mousemove(event) {
+            y = event.screenY - startY;
+            x = event.screenX - startX;
+            element.css({
+              top: y + 'px',
+              left:  x + 'px'
+            });
+          }
+
+          function mouseup() {
+            $document.unbind('mousemove', mousemove);
+            $document.unbind('mouseup', mouseup);
+          }
+        }
+      });
+  </file>
+  <file name="index.html">
+    <span draggable>Drag ME</span>
+  </file>
+</example>
+
+
+The presence of the `draggable` attribute on any element gives the element new behavior. The beauty of
+this approach is that we have taught the browser a new trick. We have extended the vocabulary of
+what the browser understands in a way which is natural to anyone who is familiar with HTML
+principles.
+
+
+# Understanding View
+
+There are many templating systems out there. Most of them consume a static string template and
+combine it with data, resulting in a new string. The resulting text is then `innerHTML`ed into
+an element.
+
+<img src="img/One_Way_Data_Binding.png">
+
+This means that any changes to the data need to be re-merged with the template and then
+`innerHTML`ed into the DOM. Some of the issues with this approach are: reading user input and merging it with data,
+clobbering user input by overwriting it, managing the whole update process, and lack of behavior
+expressiveness.
+
+Angular is different. The Angular compiler consumes the DOM with directives, not string templates.
+The result is a linking function, which when combined with a scope model results in a live view. The
+view and scope model bindings are transparent. No action from the developer is needed to update
+the view. And because no `innerHTML` is used there are no issues of clobbering user input.
+Furthermore, Angular directives can contain not just text bindings, but behavioral constructs as
+well.
+
+<img src="img/Two_Way_Data_Binding.png">
+
+The Angular approach produces a stable DOM. This means that the DOM element instance bound to a model
+item instance does not change for the lifetime of the binding. This means that the code can get
+hold of the elements and register event handlers and know that the reference will not be destroyed
+by template data merge.
@@ -0,0 +1,451 @@
+@ngdoc overview
+@name Conceptual Overview
+@description
+
+# Overview
+
+This document gives a quick overview of the main angular components and how they work together.
+These are:
+
+  * {@link concepts#startup startup} - bring up hello world
+  * {@link concepts#runtime runtime} - overview of angular runtime
+  * {@link concepts#scope scope} - the glue between the view and the controller
+  * {@link concepts#controller controller} - application behavior
+  * {@link concepts#model model} - your application data
+  * {@link concepts#view view} - what the user sees
+  * {@link concepts#directives directives} - extend HTML vocabulary
+  * {@link concepts#filters filters} - format the data in user locale
+  * {@link concepts#injector injector} - assembles your application
+  * {@link concepts#module module} - configures the injector
+  * {@link concepts#angular_namespace `$`} - angular namespace
+
+<a name="startup"></a>
+# Startup
+
+This is how we get the ball rolling (refer to the diagram and example below):
+
+<img class="pull-right" style="padding-left: 3em;" src="img/guide/concepts-startup.png">
+
+  1. The browser loads the HTML and parses it into a DOM
+  2. The browser loads `angular.js` script
+  3. Angular waits for `DOMContentLoaded` event
+  4. Angular looks for {@link api/ng.directive:ngApp ng-app}
+    {@link guide/directive directive}, which designates the application boundary
+  5. The {@link guide/module Module} specified in {@link
+     api/ng.directive:ngApp ng-app} (if any) is used to configure
+     the {@link api/AUTO.$injector $injector}
+  6. The {@link api/AUTO.$injector $injector} is used to create the {@link
+     api/ng.$compile $compile} service as well as {@link
+     api/ng.$rootScope $rootScope}
+  7. The {@link api/ng.$compile $compile} service is used to compile the DOM and link
+     it   with {@link api/ng.$rootScope $rootScope}
+  8. The {@link api/ng.directive:ngInit ng-init} {@link
+     guide/directive directive} assigns `World` to the `name` property on the {@link guide/scope
+     scope}
+  9. The `{{name}}` {@link api/ng.$interpolate interpolates} the expression to
+     `Hello World!`
+
+<example>
+  <file name="index.html">
+    <p ng-init=" name='World' ">Hello {{name}}!</p>
+  </file>
+</example>
+
+
+<a name="runtime"></a>
+# Runtime
+
+<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-runtime.png">
+
+The diagram and the example below describe how Angular interacts with the browser's event loop.
+
+  1. The browser's event-loop waits for an event to arrive. An event is a user interaction, timer event,
+     or network event (response from a server).
+  2. The event's callback gets executed. This enters the JavaScript context. The callback can
+      modify the DOM structure.
+  3. Once the callback executes, the browser leaves the JavaScript context and
+     re-renders the view based on DOM changes.
+
+Angular modifies the normal JavaScript flow by providing its own event processing loop. This
+splits the JavaScript into classical and Angular execution context. Only operations which are
+applied in Angular execution context will benefit from Angular data-binding, exception handling,
+property watching, etc... You can also use $apply() to enter Angular execution context from JavaScript. Keep in
+mind that in most places (controllers, services) $apply has already been called for you by the
+directive which is handling the event. An explicit call to $apply is needed only when
+implementing custom event callbacks, or when working with third-party library callbacks.
+
+  1. Enter Angular execution context by calling {@link guide/scope scope}`.`{@link
+     api/ng.$rootScope.Scope#$apply $apply}`(stimulusFn)`. Where `stimulusFn` is
+     the work you wish to do in Angular execution context.
+  2. Angular executes the `stimulusFn()`, which typically modifies application state.
+  3. Angular enters the {@link api/ng.$rootScope.Scope#$digest $digest} loop. The
+     loop is made up of two smaller loops which process {@link
+     api/ng.$rootScope.Scope#$evalAsync $evalAsync} queue and the {@link
+     api/ng.$rootScope.Scope#$watch $watch} list. The {@link
+     api/ng.$rootScope.Scope#$digest $digest} loop keeps iterating until the model
+     stabilizes, which means that the {@link api/ng.$rootScope.Scope#$evalAsync
+     $evalAsync} queue is empty and the {@link api/ng.$rootScope.Scope#$watch
+     $watch} list does not detect any changes.
+  4. The {@link api/ng.$rootScope.Scope#$evalAsync $evalAsync} queue is used to
+     schedule work which needs to occur outside of current stack frame, but before the browser's
+     view render. This is usually done with `setTimeout(0)`, but the `setTimeout(0)` approach
+     suffers from slowness and may cause view flickering since the browser renders the view after
+     each event.
+  5. The {@link api/ng.$rootScope.Scope#$watch $watch} list is a set of expressions
+     which may have changed since last iteration. If a change is detected then the `$watch`
+     function is called which typically updates the DOM with the new value.
+  6. Once the Angular {@link api/ng.$rootScope.Scope#$digest $digest} loop finishes
+     the execution leaves the Angular and JavaScript context. This is followed by the browser
+     re-rendering the DOM to reflect any changes.
+
+
+Here is the explanation of how the `Hello world` example achieves the data-binding effect when the
+user enters text into the text field.
+
+  1. During the compilation phase:
+     1. the {@link api/ng.directive:ngModel ng-model} and {@link
+        api/ng.directive:input input} {@link guide/directive
+        directive} set up a `keydown` listener on the `<input>` control.
+     2. the {@link api/ng.$interpolate &#123;&#123;name&#125;&#125; } interpolation
+        sets up a {@link api/ng.$rootScope.Scope#$watch $watch} to be notified of
+        `name` changes.
+  2. During the runtime phase:
+     1. Pressing an '`X`' key causes the browser to emit a `keydown` event on the input control.
+     2. The {@link api/ng.directive:input input} directive
+        captures the change to the input's value and calls {@link
+        api/ng.$rootScope.Scope#$apply $apply}`("name = 'X';")` to update the
+        application model inside the Angular execution context.
+     3. Angular applies the `name = 'X';` to the model.
+     4. The {@link api/ng.$rootScope.Scope#$digest $digest} loop begins
+     5. The {@link api/ng.$rootScope.Scope#$watch $watch} list detects a change
+        on the `name` property and notifies the {@link api/ng.$interpolate
+        &#123;&#123;name&#125;&#125; } interpolation, which in turn updates the DOM.
+     6. Angular exits the execution context, which in turn exits the `keydown` event and with it
+        the JavaScript execution context.
+     7. The browser re-renders the view with update text.
+
+<example>
+  <file name="index.html">
+    <input ng-model="name">
+    <p>Hello {{name}}!</p>
+  </file>
+</example>
+
+<a name="scope"></a>
+#Scope
+
+The {@link guide/scope scope} is responsible for detecting changes to the model section and
+provides the execution context for expressions. The scopes are nested in a hierarchical structure
+which closely follow the DOM structure. (See individual directive documentation to see which
+directives cause a creation of new scopes.)
+
+The following example demonstrates how the `name` {@link guide/expression expression} will evaluate
+into a different value depending on which scope it is evaluated in. The example is followed by
+a diagram depicting the scope boundaries.
+
+<div class="show-scope">
+<example>
+  <file name="index.html">
+    <div ng-controller="GreetCtrl">
+      Hello {{name}}!
+    </div>
+    <div ng-controller="ListCtrl">
+      <ol>
+        <li ng-repeat="name in names">{{name}}</li>
+      </ol>
+    </div>
+  </file>
+  <file name="script.js">
+    function GreetCtrl($scope) {
+      $scope.name = 'World';
+    }
+
+    function ListCtrl($scope) {
+      $scope.names = ['Igor', 'Misko', 'Vojta'];
+    }
+  </file>
+  <file name="style.css">
+    .show-scope .doc-example-live.ng-scope,
+    .show-scope .doc-example-live .ng-scope  {
+      border: 1px solid red;
+      margin: 3px;
+    }
+  </file>
+</example>
+</div>
+
+<img class="center" src="img/guide/concepts-scope.png">
+
+
+<a name="controller"></a>
+# Controller
+
+<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-controller.png">
+
+A controller is the code behind the view. Its job is to construct the model and publish it to the
+view along with callback methods. The view is a projection of the scope onto the template (the
+HTML). The scope is the glue which marshals the model to the view and forwards the events to the
+controller.
+
+The separation of the controller and the view is important because:
+
+  * The controller is written in JavaScript. JavaScript is imperative. Imperative is a good fit
+    for specifying application behavior. The controller should not contain any rendering
+    information (DOM references or HTML fragments).
+  * The view template is written in HTML. HTML is declarative. Declarative is a good fit for
+    specifying UI. The View should not contain any behavior.
+  * Since the controller is unaware of the view, there could be many views for the same
+    controller. This is important for re-skinning, device specific views (i.e. mobile vs desktop),
+    and testability.
+
+<example>
+  <file name="index.html">
+    <div ng-controller="MyCtrl">
+      Hello {{name}}!
+      <button ng-click="action()">
+        OK
+      </button>
+    </div>
+  </file>
+  <file name="script.js">
+    function MyCtrl($scope) {
+      $scope.action = function() {
+        $scope.name = 'OK';
+      }
+
+      $scope.name = 'World';
+    }
+  </file>
+</example>
+
+
+<a name="model"></a>
+# Model
+
+<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-model.png">
+
+The model is the data which is merged with the template to produce the view. To be able to
+render the model into the view, the model has to be able to be referenced from the scope. Unlike many
+other frameworks Angular makes no restrictions or requirements on the model. There are no classes
+to inherit from or special accessor methods for accessing or changing the model. The model can be
+primitive, object hash, or a full object Type. In short the model is a plain JavaScript object.
+
+
+<a name="view"></a>
+# View
+
+<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-view.png">
+
+The view is what the user sees. The view begins its life as a template, is merged with the
+model and finally rendered into the browser DOM. Angular takes a very different approach to
+rendering the view compared to most other templating systems.
+
+  * **Others** - Most templating systems begin as an HTML string with special templating markup.
+    Often the template markup breaks the HTML syntax which means that the template can not be
+    edited by an HTML editor. The template string is then parsed by the template engine, and
+    merged with the data. The result of the merge is an HTML string. The HTML string is then
+    written to the browser using the `.innerHTML`, which causes the browser to render the HTML.
+    When the model changes the whole process needs to be repeated. The granularity of the template
+    is the granularity of the DOM updates. The key here is that the templating system manipulates
+    strings.
+  * **Angular** - Angular is different, since its templating system works on DOM objects not on
+    strings. The template is still written in an HTML string, but it is HTML (not HTML with
+    template sprinkled in.) The browser parses the HTML into the DOM, and the DOM becomes the input to
+    the template engine known as the {@link api/ng.$compile compiler}. The compiler
+    looks for {@link guide/directive directives} which in turn set up {@link
+    api/ng.$rootScope.Scope#$watch watches} on the model. The result is a
+    continuously updating view which does not need template model re-merging. Your model becomes
+    the single source-of-truth for your view.
+
+<example>
+  <file name="index.html">
+    <div ng-init="list = ['Chrome', 'Safari', 'Firefox', 'IE'] ">
+      <input ng-model="list" ng-list> <br>
+      <input ng-model="list" ng-list> <br>
+      <pre>list={{list}}</pre> <br>
+      <ol>
+        <li ng-repeat="item in list">
+          {{item}}
+        </li>
+      </ol>
+    </div>
+  </file>
+</example>
+
+
+<a name="directives"></a>
+# Directives
+
+A directive is a behavior or DOM transformation which is triggered by the presence of a custom attribute,
+element name, class name or comment. A directive allows you to extend the HTML vocabulary in a
+declarative fashion. Following is an example which enables data-binding for the `contenteditable`
+in HTML.
+
+<example module="directive">
+  <file name="script.js">
+    angular.module('directive', []).directive('contenteditable', function() {
+      return {
+        require: 'ngModel',
+        link: function(scope, elm, attrs, ctrl) {
+          // view -> model
+          elm.bind('blur', function() {
+            scope.$apply(function() {
+              ctrl.$setViewValue(elm.html());
+            });
+          });
+
+          // model -> view
+          ctrl.$render = function(value) {
+            elm.html(value);
+          };
+
+          // load init value from DOM
+          ctrl.$setViewValue(elm.html());
+        }
+      };
+    });
+  </file>
+  <file name="index.html">
+    <div contentEditable="true" ng-model="content">Edit Me</div>
+    <pre>model = {{content}}</pre>
+  </file>
+  <file name="style.css">
+    div[contentEditable] {
+      cursor: pointer;
+      background-color: #D0D0D0;
+      margin-bottom: 1em;
+      padding: 1em;
+    }
+  </file>
+</example>
+
+<a name="filters"></a>
+# Filters
+
+{@link api/ng.$filter Filters} perform data transformation. Typically
+they are used in conjunction with the locale to format the data in locale specific output.
+They follow the spirit of UNIX filters and use similar syntax `|` (pipe).
+
+<example>
+  <file name="index.html">
+    <div ng-init="list = ['Chrome', 'Safari', 'Firefox', 'IE'] ">
+      Number formatting: {{ 1234567890 | number }} <br>
+      array filtering <input ng-model="predicate">
+      {{ list | filter:predicate | json }}
+    </div>
+  </file>
+</example>
+
+
+<a name="module"></a>
+<a name="injector"></a>
+# Modules and the Injector
+
+<img class="pull-right" style="padding-left: 3em; padding-bottom: 1em;" src="img/guide/concepts-module-injector.png">
+
+The {@link api/AUTO.$injector injector} is a service locator. There is a single
+{@link api/AUTO.$injector injector} per Angular {@link
+api/ng.directive:ngApp application}. The {@link
+api/AUTO.$injector injector} provides a way to look up an object instance by its
+name. The injector keeps an internal cache of all objects so that repeated calls to get the same
+object name result in the same instance. If the object does not exist, then the {@link
+api/AUTO.$injector injector} asks the instance factory to create a new instance.
+
+A {@link api/angular.Module module} is a way to configure the injector's instance factory, known
+as a {@link api/AUTO.$provide provider}.
+
+<pre>
+  // Create a module
+  var myModule = angular.module('myModule', [])
+
+  // Configure the injector
+  myModule.factory('serviceA', function() {
+    return {
+      // instead of {}, put your object creation here
+    };
+  });
+
+  // create an injector and configure it from 'myModule'
+  var $injector = angular.injector(['myModule']);
+
+  // retrieve an object from the injector by name
+  var serviceA = $injector.get('serviceA');
+
+  // always true because of instance cache
+  $injector.get('serviceA') === $injector.get('serviceA');
+</pre>
+
+
+But the real magic of the {@link api/AUTO.$injector injector} is that it can be
+used to {@link api/AUTO.$injector#invoke call} methods and {@link
+api/AUTO.$injector#instantiate instantiate} types. This subtle feature is what
+allows the methods and types to ask for their dependencies instead of having to look for them.
+
+<pre>
+  // You write functions such as this one.
+  function doSomething(serviceA, serviceB) {
+    // do something here.
+  }
+
+  // Angular provides the injector for your application
+  var $injector = ...;
+
+  ///////////////////////////////////////////////
+  // the old-school way of getting dependencies.
+  var serviceA = $injector.get('serviceA');
+  var serviceB = $injector.get('serviceB');
+
+  // now call the function
+  doSomething(serviceA, serviceB);
+
+  ///////////////////////////////////////////////
+  // the cool way of getting dependencies.
+  // the $injector will supply the arguments to the function automatically
+  $injector.invoke(doSomething); // This is how the framework calls your functions
+</pre>
+
+Notice that the only thing you needed to write was the function, and list the dependencies in the
+function arguments. When angular calls the function, it will use the {@link
+api/AUTO.$injector#invoke call} which will automatically fill the function
+arguments.
+
+Examine the `ClockCtrl` below, and notice how it lists the dependencies in the constructor. When the
+{@link api/ng.directive:ngController ng-controller} instantiates
+the controller it automatically provides the dependencies. There is no need to create
+dependencies, look for dependencies, or even get a reference to the injector.
+
+<example module="timeExampleModule">
+  <file name="index.html">
+    <div ng-controller="ClockCtrl">
+      Current time is: {{ time.now }}
+    </div>
+  </file>
+  <file name="script.js">
+    angular.module('timeExampleModule', []).
+      // Declare new object called time,
+      // which will be available for injection
+      factory('time', function($timeout) {
+        var time = {};
+
+        (function tick() {
+          time.now = new Date().toString();
+          $timeout(tick, 1000);
+        })();
+        return time;
+      });
+
+    // Notice that you can simply ask for time
+    // and it will be provided. No need to look for it.
+    function ClockCtrl($scope, time) {
+      $scope.time = time;
+    }
+  </file>
+</example>
+
+
+<a name="angular_namespace"></a>
+# Angular Namespace
+
+To prevent accidental name collision, Angular prefixes names of objects which could potentially
+collide with `$`. Please do not use the `$` prefix in your code as it may accidentally collide
+with Angular code.
@@ -1,49 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Initializing Angular: Automatic Initialization
-@description
-
-Angular initializes automatically when you load the angular script into your page that contains an element
-with `ng-app` directive:
-
-<pre>
-<!doctype html>
-<html ng-app>
-  <head>
-    <script src="angular.js"></script>
-  </head>
-  <body>
-    I can add: {{ 1+2 }}.
-  </body>
-</html>
-</pre>
-
-From a high-level view, this is what happens during angular's automatic initialization process:
-
-1. The browser loads the page, and then runs the angular script. Angular waits for the
-`DOMContentLoaded` (or 'Load') event to attempt to bootstrap.
-
-2. Angular looks for the `ng-app` directive. If found it then proceeds to compile the DOM element and its children.
-Optionally the `ng-app` may specify a {@link api/angular.module module} to load before the compilation. For details on
-how the compiler works, see {@link dev_guide.compiler Angular HTML Compiler}.
-
-
-## Initialization Options
-
-The reason why `ng-app` exists is because angular should not assume that the entire HTML
-document should be processed just because the `angular.js` script is included. In order to compile
-only a part of the document set the `ng-app` on the root element of this portion.
-
-## Global Angular Object
-
-The angular script creates a single global variable `angular` in the global namespace. All angular
-APIs are bound to fields of this global object.
-
-
-## Related Topics
-
-* {@link dev_guide.bootstrap Initializing Angular}
-* {@link dev_guide.bootstrap.manual_bootstrap Manual Initialization}
-
-## Related API
-
-{@link api/angular.module.ng.$compile Compiler API}
@@ -1,46 +0,0 @@
-@ngdoc overview
-@name  Developer Guide: Initializing Angular: Manual Initialization
-@description
-
-Letting angular handle the initialization process (bootstrapping) is a handy way to start using
-angular, but advanced users who want more control over the initialization process can choose to use
-the manual bootstrapping method instead.
-
-The best way to get started with manual bootstrapping is to look at the what happens when you use
-{@link api/angular.module.ng.$compileProvider.directive.ng-app ng-app}, by showing each step of the process
-explicitly.
-
-<pre>
-<!doctype html>
-<html>
-<head>
-  <script src="http://code.angularjs.org/angular.js"></script>
-  <script>
-     angular.element(document).ready(function() {
-       angular.bootstrap(document);
-     });
-  </script>
-</head>
-<body>
-Hello {{'World'}}!
-</body>
-</html>
-</pre>
-
-This is the sequence that your code should follow if you bootstrap angular on your own:
-
-1. After the page is loaded, find the root of the HTML template, which is typically the root of
-the document.
-2. Call {@link api/angular.bootstrap} to  {@link dev_guide.compiler compile} the template into
-an executable, bi-directionally bound application.
-
-
-## Related Topics
-
-* {@link dev_guide.bootstrap Initializing Angular}
-* {@link dev_guide.bootstrap.auto_bootstrap Automatic Initialization}
-* {@link dev_guide.compiler Angular HTML compiler}
-
-## Related API
-
-{@link api/angular.module.ng.$compile Compiler API}
@@ -1,65 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Initializing Angular
-@description
-
-Initializing angular consists of loading the `angular.js` script in your page, and specifying how
-angular should process and manage the page. To initialize angular you do the following:
-
-* Specify the angular namespace in the `<html>` page
-* Choose which flavor of angular script to load (debug or production)
-* Specify whether or not angular should process and manage the page automatically (`ng-app`)
-
-The simplest way to initialize angular is to load the angular script and tell angular to compile
-and manage the whole page. You do this as follows:
-
-<pre>
-<!doctype html>
-<html ng-app>
-  <head>
-    ...
-  </head>
-  <body>
-    ...
-    <script src="angular.js">
-  </body>
-</pre>
-
-
-## Specifying the Angular Namespace
-
-        <html xmlns:ng="http://angularjs.org">
-
-You need to add the angular namespace declaration if you use `ng:something` style of declaring
-angular directives and you write your templates as XHTML. Or when you are targeting Internet
-Explorer older than version 9 (because older versions of IE do not render namespace
-properly for either HTML or XHTML). For more info please read {@link ie Internet Explorer
-Compatibility} doc.
-
-
-## Creating Your Own Namespaces
-
-When you are ready to define your own {@link api/angular.module.ng.$compileProvider.directive
-directive}, you may chose to create your own namespace in addition to specifying the angular
-namespace. You use your own namespace to form the fully qualified name for directives that you
-create.
-
-For example, you could map the alias `my` to your domain, and create a directive called `my:directive`.
-To create your own namespace, simply add another `xmlns` tag to your page, create an alias, and set
-it to your unique domain:
-
-        <html xmlns:ng="http://angularjs.org" xmlns:my="http://mydomain.com">
-
-
-## Loading the Angular Bootstrap Script
-
-The angular bootstrap script comes in two flavors; a debug script, and a production script:
-
-* angular-[version].js - This is a human-readable file, suitable for development and debugging.
-* angular-[version].min.js - This is a compressed and obfuscated file, suitable for use in
-production.
-
-
-## Related Topics
-
-* {@link dev_guide.bootstrap.auto_bootstrap Automatic Initialization}
-* {@link dev_guide.bootstrap.manual_bootstrap Manual Initialization}
@@ -1,23 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler
-@description
-
-The core of angular is its HTML compiler.  The compiler processes angular directives allowing them
-to transform a static HTML page into a dynamic web application.
-
-The default HTML transformations that the angular compiler provides are useful for building generic
-apps, but you can also extend the compiler to create a domain-specific language for building
-specific types of web applications.
-
-All compilation takes place in the web browser; no server is involved.
-
-
-## Related Topics
-
-* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
-* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile Angular Compiler API}
-* {@link api/angular.module.ng.$compileProvider.directive Directives API}
@@ -1,16 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler: Testing a New DOM Element
-@description
-
-
-"Testing, testing, come in, over?"
-
-
-## Related Topics
-
-* {@link dev_guide.compiler Angular HTML Compiler}
-* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile $compile()}
@@ -1,34 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works
-@description
-
-The {@link api/angular.module.ng.$compile compiler} is responsible for applying
-{@link api/angular.module.ng.$compileProvider.directive directives} to the HTML. The directives
-extend the behavior of HTML elements and can effect the DOM structure, presentation, and behavior.
-This allows Angular to teach the browser new tricks.
-
-The compilation starts at the root element and proceeds in a depth-first order. As the compiler
-visits each node it collects the directives, orders them by priority and executes their compile
-function. The result of the compilation process is a linking function. The linking function
-can be used on the template clones to quickly bind the directives with the scope.
-
-The result of the compilation process is a live view. We say 'live' since any changes to the
-model attached to the {@link api/angular.module.ng.$rootScope.Scope scope} are reflected in the view,
-and any changes in the view are reflected in the scope. This makes the scope the 'single source of
-truth'.
-
-Since directives allow attachment of behavior to the HTML, the angular philosophy is to use the
-HTML as Domain Specific Language (DSL) when building an application. For example it may be useful
-to declare `TabPanel` directive, or `KeyboardShortcut` directive when for an application.
-
-For details on how directives are created see {@link api/angular.module.ng.$compileProvider.directive
-directives}
-
-## Related Topics
-
-* {@link dev_guide.compiler Angular HTML Compiler}
-* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile $compile()}
@@ -1,32 +0,0 @@
-@ngdoc overview
-@name Developer Guide: About Dependency Injection (DI)
-@description
-
-Dependency Injection (DI) is an object-oriented software design pattern that supports the
-decoupling and dependency management of application components.
-
-The idea behind DI is to decouple each component from all of the other components that it depends
-on to do its particular job. The way this is done in DI is by moving the responsibility for
-managing dependencies out of each individual component and into a provider component. The provider
-(or injector) component manages the life cycles and dependencies for all of the other components in
-an application.
-
-Angular has a built-in dependency management subsystem that helps to make your applications easier
-to develop, understand, and test.
-
-For more information on DI in general, see {@link http://en.wikipedia.org/wiki/Dependency_injection
-Dependency Injection} at Wikipedia, and {@link http://martinfowler.com/articles/injection.html
-Inversion of Control} by Martin Fowler, or read about DI in your favorite software design pattern
-book.
-
-
-## Related Topics
-
-* {@link dev_guide.di.understanding_di Understanding DI in Angular}
-* {@link dev_guide.services Angular Services}
-
-
-## Related API
-
-* {@link api/angular.module.ng Service API}
-* {@link api/angular.injector Angular Injector API}
@@ -1,193 +0,0 @@
-@ngdoc overview
-@name Developer Guide: DI: Understanding DI in Angular
-@description
-
-
-While DI is widely used in statically typed languages such as Java or C++, it has not been widely
-used in JavaScript. Angular brings the benefits of DI into JavaScript apps.
-
-In angular, DI is implemented as a subsystem that manages dependencies between services,
-controllers, widgets, and filters.
-
-Services are objects that handle common tasks in web applications. Angular provides several {@link
-api/angular.module.ng built-in services}, and you can create your
-{@link dev_guide.services.creating_services own custom services}.
-
-The main job of angular's DI subsystem is to provide services to angular components that depend on
-them. The way the DI subsystem provides services is as follows: all services are registered with
-angular's {@link api/angular.module.ng service API}, and all components that depend on services
-define those dependencies as a property (`$inject`). With this information, the DI subsystem
-manages the creation of service objects and the provision of those objects to the components that
-need them, at the time they need them. The following illustration steps through the sequence of
-events:
-
-<img src="img/guide/di_sequence_final.png">
-
-In the illustration above, the dependency injection sequence proceeds as follows:
-
-1. Module "phonecat" is created and all the service providers are registered with this module.
-   (the "ng" module is created by Angular behind the scenes as well)
-2. `ng-app` triggers bootstrap sequence on given element, during which angular creates injector,
-loads "phonecat" and "ng" modules and compiles the template.
-3. The `ng-controller` directive implicitly creates a new child scope and instantiates
-`PhoneListCtrl` controller.
-4. Injector identifies the `$http` service as `PhoneListCtrl` controller's only dependency.
-5. Injector checks its instances cache whether the `$http` service has already been instantiated.
-If not uses the provider from the available modules to construct it.
-6. Injector provides the instance of `$http` service to the `PhoneListCtrl` controller constructor.
-
-
-## How Scope Relates to DI
-
-The root scope of the application is just a service that is available for injection to any part of
-the application under the service name "$rootScope".
-
-
-## Inferring dependencies from the signature of the factory function or constructor
-
-**EXPERIMENTAL FEATURE**: This is an experimental feature. See the important note at the end of
-this section for drawbacks.
-
-We resort to `$inject` and our own annotation because there is no way in JavaScript to get a list
-of arguments. Or is there? It turns out that calling `.toString()` on a function returns the
-function declaration along with the argument names as shown below:
-
-<pre>
-function myFn(a,b){}
-expect(myFn.toString()).toEqual('function myFn(a,b){}');
-</pre>
-
-This means that angular can infer the function names after all and use that information to generate
-the `$inject` annotation automatically. Therefore the following two function definitions are
-equivalent:
-
-<pre>
-// given a user defined service
-angular.module('module1', [], function($provide) {
-  $provide.factory('serviceA', ...);
-});
-
-// inject '$window', 'serviceA', curry 'name';
-function fnA($window, serviceA, name){};
-fnA.$inject = ['$window', 'serviceA'];
-
-// inject '$window', 'serviceA', curry 'name';
-function fnB($window, serviceA_, name){};
-// implies: fnB.$inject = ['$window', 'serviceA'];
-</pre>
-
-If angular does not find a `$inject` annotation on the function, then it calls the `.toString()`
-method and tries to infer what should be injected by using function argument names as dependency
-identifiers.
-
-**IMPORTANT**
-Minifiers/obfuscators change the names of function arguments and will therefore break the `$inject`
-inference. For this reason, either explicitly declare the `$inject` or do not use
-minifiers/obfuscators. In the future, we may provide a pre-processor which will scan the source
-code and insert the `$inject` into the source code so that it can be minified/obfuscated.
-
-
-### Dependency inference and variable name shadowing
-
-During inference, the injector considers argument names with leading and trailing underscores to be
-equivivalent to the name without these underscores. For example `_fooSvc_` argument name is treated
-as if it was `fooSvc`, this is useful especially in tests where variable name shadowing can cause
-some friction. This is best illustrated on examples:
-
-When testing a service, it's common to need a reference to it in every single test. This can be
-done in jasmine with DI inference like this:
-
-<pre>
-describe('fooSvc', function() {
-  it('should do this thing', inject(function(fooSvc) {
-    //test fooSvc
-  }));
-
-  it('should do that thing', inject(function(fooSvc) {
-    //test fooSvc
-  }));
-
-  // more its
-});
-</pre>
-
-... but having to inject the service over and over gets easily tiresome.
-
-It's likely better to rewrite these tests with a use of jasmine's `beforeEach`:
-
-<pre>
-describe('fooSvc', function() {
-  var fooSvc;
-
-  beforeEach(inject(function(fooSvc) {
-    fooSvc = fooSvc; // DOESN'T WORK! outer fooSvc is being shadowed
-  }));
-
-  it('should do this thing', function() {
-    //test fooSvc
-  });
-
-  it('should do that thing', function() {
-    //test fooSvc
-  });
-
-  // more its
-});
-</pre>
-
-This obviously won't work because `fooSvc` variable in the describe block is being shadowed by the
-`fooSvc` argument of the beforeEach function. So we have to resort to alternative solutions, like
-for example use of array notation to annotate the beforeEach fn:
-
-<pre>
-describe('fooSvc', function() {
-  var fooSvc;
-
-  beforeEach(inject(['fooSvc', function(fooSvc_) {
-    fooSvc = fooSvc_;
-  }]));
-
-  it('should do this thing', function() {
-    //test fooSvc
-  });
-
-  it('should do that thing', function() {
-    //test fooSvc
-  });
-});
-</pre>
-
-
-That's better, but it's still annoying, especially if you have many services to inject.
-
-To resolve this shadowing problem, the injector considers `_fooSvc_` argument names equal to
-`fooSvc`, so the test can be rewritten like this:
-
-<pre>
- describe('fooSvc', function() {
-   var fooSvc;
-
-   beforeEach(inject(function(_fooSvc_) {
-     fooSvc = _fooSvc_;
-   }));
-
-   it('should do this thing', function() {
-     //test fooSvc
-   });
-
-   it('should do that thing', function() {
-     //test fooSvc
-   });
-
-   // more its
- });
-</pre>
-
-
-## Related Topics
-
-* {@link dev_guide.services Angular Services}
-
-## Related API
-
-* {@link api/angular.module.ng Services API}
@@ -1,53 +0,0 @@
-@ngdoc overview
-@name Developer Guide: DI: Using DI in Controllers
-@description
-
-The most common place to use dependency injection in angular applications is in {@link
-dev_guide.mvc.understanding_controller controllers}. Here is a simple example:
-
-<pre>
-function MyController($route){
- // configure the route service
- $route.when(...);
-}
-MyController.$inject = ['$route'];
-</pre>
-
-In this example, the `MyController` constructor function takes one argument, the {@link
-api/angular.module.ng.$route $route} service. Angular is then responsible for supplying the instance
-of `$route` to the controller when the constructor is instantiated. There are two ways to cause
-controller instantiation – by configuring routes with the `$route` service, or by referencing the
-controller from the HTML template, as follows:
-
-<pre>
-<!doctype html>
-<html ng-controller="MyController" ng-app>
-<script src="http://code.angularjs.org/angular.min.js"></script>
-<body>
- ...
-</body>
-</html>
-</pre>
-
-When angular is instantiating your controller, it needs to know what services, if any, should be
-injected (passed in as arguments) into the controller. Since there is no reflection in JavaScript,
-we have to supply this information to angular in the form of an additional property on the
-controller constructor function called `$inject`. Think of it as annotations for JavaScript.
-
-<pre>
-MyController.$inject = ['$route'];
-</pre>
-
-The information in `$inject` is then used by the {@link api/angular.injector injector} to call the
-function with the correct arguments.
-
-
-## Related Topics
-
-* {@link dev_guide.di About Dependency Injection}
-* {@link dev_guide.di.understanding_di Understanding Dependency Injection in Angular}
-* {@link dev_guide.services Angular Services}
-
-## Related API
-
-* {@link api/angular.injector Angular Injector API}
@@ -11,7 +11,7 @@ that will help you verify the health of your Angular application.

 # Overview
 You will write scenario tests in JavaScript, which describe how your application should behave,
-given a certain interaction in a specific state. A scenario is comprised of one or more it  blocks
+given a certain interaction in a specific state. A scenario is comprised of one or more `it` blocks
 (you can think of these as the requirements of your application), which in turn are made of
 **commands** and **expectations**. Commands tell the Runner to do something with the application
 (such as navigate to a page or click on a button), and expectations tell the Runner to assert
@@ -38,14 +38,14 @@ it('should filter results', function() {
 });
 </pre>
 This scenario describes the requirements of a Buzz Client, specifically, that it should be able to
-filter the stream of the user. It starts by entering a value in the 'user' input field, clicking
+filter the stream of the user. It starts by entering a value in the input field with ng-model="user", clicking
 the only button on the page, and then it verifies that there are 10 items listed. It then enters
-'Bees' in the 'filterText' input field and verifies that the list is reduced to a single item.
+'Bees' in the input field with ng-model='filterText'  and verifies that the list is reduced to a single item.

 The API section below lists the available commands and expectations for the Runner.

 # API
-Source: {@link https://github.com/angular/angular.js/blob/master/src/scenario/dsl.js}
+Source: {@link https://github.com/angular/angular.js/blob/master/src/ngScenario/dsl.js}

 ## pause()
 Pauses the execution of the tests until you call `resume()` in the console (or click the resume
@@ -78,26 +78,27 @@ Returns the window.location.search of the currently loaded page in the test fram
 Returns the window.location.hash (without `#`) of the currently loaded page in the test frame.

 ## browser().location().url()
-Returns the {@link api/angular.module.ng.$location $location.url()} of the currently loaded page in
+Returns the {@link api/ng.$location $location.url()} of the currently loaded page in
 the test frame.

 ## browser().location().path()
-Returns the {@link api/angular.module.ng.$location $location.path()} of the currently loaded page in
+Returns the {@link api/ng.$location $location.path()} of the currently loaded page in
 the test frame.

 ## browser().location().search()
-Returns the {@link api/angular.module.ng.$location $location.search()} of the currently loaded page
+Returns the {@link api/ng.$location $location.search()} of the currently loaded page
 in the test frame.

 ## browser().location().hash()
-Returns the {@link api/angular.module.ng.$location $location.hash()} of the currently loaded page in
+Returns the {@link api/ng.$location $location.hash()} of the currently loaded page in
 the test frame.

 ## expect(future).{matcher}
 Asserts the value of the given `future` satisfies the `matcher`. All API statements return a
 `future` object, which get a `value` assigned after they are executed. Matchers are defined using
 `angular.scenario.matcher`, and they use the value of futures to run the expectation. For example:
-`expect(browser().location().href()).toEqual('http://www.google.com')`
+`expect(browser().location().href()).toEqual('http://www.google.com')`. Available matchers
+are presented further down this document.

 ## expect(future).not().{matcher}
 Asserts the value of the given `future` satisfies the negation of the `matcher`.
@@ -109,20 +110,20 @@ Scopes the next DSL element selection.
 Returns the value of the first binding matching the given `name`.

 ## input(name).enter(value)
-Enters the given `value` in the text field with the given `name`.
+Enters the given `value` in the text field with the corresponding ng-model `name`.

 ## input(name).check()
-Checks/unchecks the checkbox with the given `name`.
+Checks/unchecks the checkbox with the corresponding ng-model `name`.

 ## input(name).select(value)
-Selects the given `value` in the radio button with the given `name`.
+Selects the given `value` in the radio button with the corresponding ng-model `name`.

 ## input(name).val()
-Returns the current value of an input field with the given `name`.
+Returns the current value of an input field with the corresponding ng-model `name`.

 ## repeater(selector, label).count()
 Returns the number of rows in the repeater matching the given jQuery `selector`. The `label` is
-used for test ouput.
+used for test output.

 ## repeater(selector, label).row(index)
 Returns an array with the bindings in the row at the given `index` in the repeater matching the
@@ -133,10 +134,10 @@ Returns an array with the values in the column with the given `binding` in the r
 the given jQuery `selector`. The `label` is used for test output.

 ## select(name).option(value)
-Picks the option with the given `value` on the select with the given `name`.
+Picks the option with the given `value` on the select with the given ng-model `name`.

-## select(name).option(value1, value2...)
-Picks the options with the given `values` on the multi select with the given `name`.
+## select(name).options(value1, value2...)
+Picks the options with the given `values` on the multi select with the given ng-model `name`.

 ## element(selector, label).count()
 Returns the number of elements that match the given jQuery `selector`. The `label` is used for test
@@ -175,4 +176,133 @@ Executes the `method` passing in `key` and `value` on the element matching the g
 JavaScript is a dynamically typed language which comes with great power of expression, but it also
 come with almost no-help from the compiler. For this reason we feel very strongly that any code
 written in JavaScript needs to come with a strong set of tests. We have built many features into
-angular which makes testing your angular applications easy. So there is no excuse for not do it.
+angular which makes testing your angular applications easy. So there is no excuse for not testing.
+
+# Matchers
+
+Matchers are used in combination with the `expect(...)` function as described above and can
+be negated with `not()`. For instance: `expect(element('h1').text()).not().toEqual('Error')`.
+
+Source: {@link https://github.com/angular/angular.js/blob/master/src/ngScenario/matchers.js}
+
+<pre>
+// value and Object comparison following the rules of angular.equals().
+expect(value).toEqual(value)
+
+// a simpler value comparison using ===
+expect(value).toBe(value)
+
+// checks that the value is defined by checking its type.
+expect(value).toBeDefined()
+
+// the following two matchers are using JavaScript's standard truthiness rules
+expect(value).toBeTruthy()
+expect(value).toBeFalsy()
+
+// verify that the value matches the given regular expression. The regular
+// expression may be passed in form of a string or a regular expression
+// object.
+expect(value).toMatch(expectedRegExp)
+
+// a check for null using ===
+expect(value).toBeNull()
+
+// Array.indexOf(...) is used internally to check whether the element is
+// contained within the array.
+expect(value).toContain(expected)
+
+// number comparison using < and >
+expect(value).toBeLessThan(expected)
+expect(value).toBeGreaterThan(expected)
+</pre>
+
+# Example
+See the {@link https://github.com/angular/angular-seed angular-seed} project for more examples.
+
+## Conditional actions with element(...).query(fn)
+
+E2E testing with angular scenario is highly asynchronous and hides a lot of complexity by
+queueing actions and expectations that can handle futures. From time to time, you might need
+conditional assertions or element selection. Even though you should generally try to avoid this
+(as it is can be sign for unstable tests), you can add conditional behavior with
+`element(...).query(fn)`. The following code listing shows how this function can be used to delete
+added entries (where an entry is some domain object) using the application's web interface.
+
+Imagine the application to be structured into two views:
+
+ 1. *Overview view* which lists all the added entries in a table and
+ 2. a *detail view* which shows the entries' details and contains a delete button. When clicking the
+    delete button, the user is redirected back to the *overview page*.
+
+<pre>
+beforeEach(function () {
+  var deleteEntry = function () {
+    browser().navigateTo('/entries');
+
+    // we need to select the <tbody> element as it might be the case that there
+    // are no entries (and therefore no rows). When the selector does not
+    // result in a match, the test would be marked as a failure.
+    element('table tbody').query(function (tbody, done) {
+      // ngScenario gives us a jQuery lite wrapped element. We call the
+      // `children()` function to retrieve the table body's rows
+      var children = tbody.children();
+
+      if (children.length > 0) {
+        // if there is at least one entry in the table, click on the link to
+        // the entry's detail view
+        element('table tbody a').click();
+        // and, after a route change, click the delete button
+        element('.btn-danger').click();
+      }
+
+      // if there is more than one entry shown in the table, queue another
+      // delete action.
+      if (children.length > 1) {
+        deleteEntry();
+      }
+
+      // remember to call `done()` so that ngScenario can continue
+      // test execution.
+      done();
+    });
+
+  };
+
+  // start deleting entries
+  deleteEntry();
+});
+</pre>
+
+In order to understand what is happening, we should emphasize that ngScenario calls are not
+immediately executed, but queued (in ngScenario terms, we would be talking about adding
+future actions). If we had only one entry in our table, then the following future actions
+would be queued:
+
+<pre>
+// delete entry 1
+browser().navigateTo('/entries');
+element('table tbody').query(function (tbody, done) { ... });
+element('table tbody a');
+element('.btn-danger').click();
+</pre>
+
+For two entries, ngScenario would have to work on the following queue:
+
+<pre>
+// delete entry 1
+browser().navigateTo('/entries');
+element('table tbody').query(function (tbody, done) { ... });
+element('table tbody a');
+element('.btn-danger').click();
+
+    // delete entry 2
+    // indented to represent "recursion depth"
+    browser().navigateTo('/entries');
+    element('table tbody').query(function (tbody, done) { ... });
+    element('table tbody a');
+    element('.btn-danger').click();
+</pre>
+
+# Caveats
+
+ngScenario does not work with apps that manually bootstrap using angular.bootstrap. You must use the ng-app directive.
@@ -1,245 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Understanding Angular Expressions
-@description
-
-Expressions are {@link dev_guide.templates.databinding bindings} that you write in HTML and embed
-in templates in order to create views in angular. Angular expressions are similar but not
-equivalent to JavaScript expressions.
-
-For example, these are all valid expressions in angular:
-
-* `1+2={{1+2}}`
-* `3*10|currency`
-* `Hello {{name}}!`
-* `Hello {{'World'}}!`
-
-
-## Angular Expressions vs. JS Expressions
-
-It might be tempting to think of angular view expressions as JavaScript expressions, but that is
-not entirely correct. Angular does not use a simple JavaScript eval of the expression text. You can
-think of angular expressions as JavaScript expressions with these differences:
-
-* **Attribute Evaluation:** evaluation of all attributes are against the current scope, not to the
-global window as in JavaScript.
-* **Forgiving:** expression evaluation is forgiving to undefined and null, unlike in JavaScript.
-* **No Control Flow Statements:** you cannot do the following from an angular expression:
-conditionals, loops, or throw.
-* **Type Augmentation:** the scope expression evaluator augments built-in types.
-* **Filters:** you can add filters to an expression, for example to convert raw data into a
-human-readable format.
-* **The $:** angular reserves this prefix to differentiate its API names from others.
-
-If, on the other hand, you do want to run arbitrary JavaScript code, you should make it a
-controller method and call that. If you want to `eval()` an angular expression from JavaScript, use
-the `Scope:$eval()` method.
-
-## Example
-<doc:example>
-<doc:source>
- 1+2={{1+2}}
-</doc:source>
-<doc:scenario>
- it('should calculate expression in binding', function() {
-   expect(binding('1+2')).toEqual('3');
- });
-</doc:scenario>
-</doc:example>
-
-You can try evaluating different expressions here:
-
-<doc:example>
-<doc:source>
- <script>
-   function Cntl2($scope) {
-     $scope.exprs = [];
-     $scope.expr = '3*10|currency';
-     $scope.addExp = function(expr) {
-        this.exprs.push(expr);
-     };
-
-     $scope.removeExp = function(index) {
-       this.exprs.splice(index, 1);
-     };
-   }
- </script>
- <div ng-controller="Cntl2" class="expressions">
-   Expression:
-   <input type='text' ng-model="expr" size="80"/>
-   <button ng-click="addExp(expr)">Evaluate</button>
-   <ul>
-    <li ng-repeat="expr in exprs">
-      [ <a href="" ng-click="removeExp($index)">X</a> ]
-      <tt>{{expr}}</tt> => <span ng-bind="$parent.$eval(expr)"></span>
-     </li>
-   </ul>
- </div>
-</doc:source>
-<doc:scenario>
- it('should allow user expression testing', function() {
-    element('.expressions :button').click();
-    var li = using('.expressions ul').repeater('li');
-    expect(li.count()).toBe(1);
-    expect(li.row(0)).toEqual(["3*10|currency", "$30.00"]);
- });
-</doc:scenario>
-</doc:example>
-
-
-# Attribute Evaluation
-
-Evaluation of all attributes takes place against the current scope. Unlike JavaScript, where names
-default to global window properties, angular expressions have to use `$window` to refer to the
-global object. For example, if you want to call `alert()`, which is defined on `window`, an
-expression must use `$window.alert()`. This is done intentionally to prevent accidental access to
-the global state (a common source of subtle bugs).
-
-<doc:example>
-<doc:source>
- <script>
-   function Cntl1($window, $scope){
-     $scope.name = 'World';
-
-     $scope.greet = function() {
-       ($window.mockWindow || $window).alert('Hello ' + this.name);
-     }
-   }
- </script>
- <div class="example2" ng-controller="Cntl1">
-   Name: <input ng-model="name" type="text"/>
-   <button ng-click="greet()">Greet</button>
- </div>
-</doc:source>
-<doc:scenario>
- it('should calculate expression in binding', function() {
-   var alertText;
-   this.addFutureAction('set mock', function($window, $document, done) {
-     $window.mockWindow = {
-       alert: function(text){ alertText = text; }
-     };
-     done();
-   });
-   element(':button:contains(Greet)').click();
-   expect(this.addFuture('alert text', function(done) {
-     done(null, alertText);
-   })).toBe('Hello World');
- });
-</doc:scenario>
-</doc:example>
-
-## Forgiving
-
-Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating `a.b.c` throws
-an exception if `a` is not an object. While this makes sense for a general purpose language, the
-expression evaluations are primarily used for data binding, which often look like this:
-
-        {{a.b.c}}
-
-It makes more sense to show nothing than to throw an exception if `a` is undefined (perhaps we are
-waiting for the server response, and it will become defined soon). If expression evaluation wasn't
-forgiving we'd have to write bindings that clutter the code, for example: `{{((a||{}).b||{}).c}}`
-
-Similarly, invoking a function `a.b.c()` on undefined or null simply returns undefined.
-
-Assignments work the same way in reverse:
-
-       a.b.c = 10
-
-...creates the intermediary objects even if a is undefined.
-
-
-## No Control Flow Statements
-
-You cannot write a control flow statement in an expression. The reason behind this is core to the
-angular philosophy that application logic should be in controllers, not in the view. If you need a
-conditional (including ternary operators), loop, or to throw from a view expression, delegate to a
-JavaScript method instead.
-
-
-## Type Augmentation
-
-Built-in types have methods like `[].push()`, but the richness of these methods is limited.
-Consider the example below, which allows you to do a simple search over a canned set of contacts.
-The example would be much more complicated if we did not have the `Array:$filter()`. There is no
-built-in method on `Array` called {@link api/angular.module.ng.$filter.filter $filter} and angular doesn't add
-it to `Array.prototype` because that could collide with other JavaScript frameworks.
-
-For this reason the scope expression evaluator augments the built-in types to make them act like
-they have extra methods. The actual method for `$filter()` is `angular.module.ng.$filter.filter()`. You can
-call it from JavaScript.
-
-Extensions: You can further extend the expression vocabulary by adding new methods to
-`angular.module.ng.$filter` or `angular.String`, etc.
-
-<doc:example>
-<doc:source>
- <div ng-init="friends = [
-   {name:'John', phone:'555-1212'},
-   {name:'Mary', phone:'555-9876'},
-   {name:'Mike', phone:'555-4321'},
-   {name:'Adam', phone:'555-5678'},
-   {name:'Julie', phone:'555-8765'}]"></div>
- Search: <input ng-model="searchText"/>
- <table class="example3">
-   <thead>
-     <tr><th>Name</th><th>Phone</th><tr>
-   </thead>
-   <tbody>
-     <tr ng-repeat="friend in friends | filter:searchText">
-       <td>{{friend.name}}</td>
-       <td>{{friend.phone}}</td>
-     </tr>
-    </tbody>
- </table>
-</doc:source>
-<doc:scenario>
- it('should filter the list', function() {
-    var tr = using('table.example3 tbody').repeater('tr');
-    expect(tr.count()).toBe(5);
-    input('searchText').enter('a');
-    expect(tr.count()).toBe(2);
-
- });
-</doc:scenario>
-</doc:example>
-
-## Filters
-
-When presenting data to the user, you might need to convert the data from its raw format to a
-user-friendly format. For example, you might have a data object that needs to be formatted
-according to the locale before displaying it to the user. You can pass expressions through a chain
-of filters like this:
-
-       name | uppercase
-
-The expression evaluator simply passes the value of name to angular.module.ng.$filter.uppercase.
-
-Chain filters using this syntax:
-
-       value | filter1 | filter2
-
-You can also pass colon-delimited arguments to filters, for example, to display the number 123 with
-2 decimal points:
-
-       123 | number:2
-
-# The $
-
-You might be wondering, what is the significance of the $ prefix? It is simply a prefix that
-angular uses, to differentiate its API names from others. If angular didn't use $, then evaluating
-`a.length()` would return undefined because neither a nor angular define such a property.
-
-Consider that in a future version of angular we might choose to add a length method, in which case
-the behavior of the expression would change. Worse yet, you the developer could create a length
-property and then we would have a collision. This problem exists because angular augments existing
-objects with additional behavior. By prefixing its additions with $ we are reserving our namespace
-so that angular developers and developers who use angular can develop in harmony without collisions.
-
-
-## Related Topics
-
-* {@link dev_guide.templates.filters Understanding Angular Filters}
-
-## Related API
-
-* {@link api/angular.module.ng.$compile Angular Compiler API}
@@ -3,16 +3,16 @@
@description

 While Model-View-Controller (MVC) has acquired different shades of meaning over the years since it
-first appeared, angular incorporates the basic principles behind the original {@link
+first appeared, Angular incorporates the basic principles behind the original {@link
 http://en.wikipedia.org/wiki/Model–view–controller MVC} software design pattern into its way of
 building client-side web applications.

-The MVC pattern greatly summarized:
+The MVC pattern summarized:

 * Separate applications into distinct presentation, data, and logic components
 * Encourage loose coupling between these components

-Along with {@link dev_guide.services services} and {@link dev_guide.di dependency injection}, MVC
+Along with {@link dev_guide.services services} and {@link di dependency injection}, MVC
 makes angular applications better structured, easier to maintain and more testable.

 The following topics explain how angular incorporates the MVC pattern into the angular way of
@@ -2,252 +2,339 @@
@name Developer Guide: About MVC in Angular: Understanding the Controller Component
@description

-In angular, a controller is a JavaScript function(type/class) that is used to augment instances of
-angular {@link dev_guide.scopes Scope}, excluding the root scope. When you or angular create a new
-child scope object via the {@link api/angular.module.ng.$rootScope.Scope#$new scope.$new} API        , there is an
-option to pass in a controller as a method argument. This will tell angular to associate the
-controller with the new scope and to augment its behavior.
+# Understanding Controllers

-Use controllers to:
+In Angular, a Controller is a JavaScript **constructor function** that is used to augment the 
+{@link scope Angular Scope}.

- Set up the initial state of a scope object.
- Add behavior to the scope object.
+When a Controller is attached to the DOM via the {@link api/ng.directive:ngController ng-controller}
+directive, Angular will instantiate a new Controller object, using the specified Controller's
+**constructor function**.  A new **child scope** will be available as an injectable parameter to the
+Controller's constructor function as `$scope`.

-# Setting up the initial state of a scope object
+Use Controllers to:

-Typically, when you create an application you need to set up an initial state for an angular scope.
+- Set up the initial state of the `$scope` object.
+- Add behavior to the `$scope` object.

-Angular applies (in the sense of JavaScript's `Function#apply`) the controller constructor function
-to a new angular scope object, which sets up an initial scope state. This means that angular never
-creates instances of the controller type (by invoking the `new` operator on the controller
-constructor). Constructors are always applied to an existing scope object.
+# Setting up the initial state of a `$scope` object

-You set up the initial state of a scope by creating model properties. For example:
+Typically, when you create an application you need to set up the initial state for the Angular
+`$scope`. You set up the initial state of a scope by attaching properties to the `$scope` object.
+The properties contain the **view model** (the model that will be presented by the view).  All the
+`$scope` properties will be available to the template at the point in the DOM where the Controller
+is registered.

-function GreetingCtrl($scope) {
- $scope.greeting = 'Hola!';
-}
+The following example shows a very simple constructor function for a Controller, `GreetingCtrl`,
+which attaches a `greeting` property containing the string `'Hola!'` to the `$scope`:

-The `GreetingCtrl` controller creates a `greeting` model which can be referred to in a template.
+<pre>
+    function GreetingCtrl($scope) {
+        $scope.greeting = 'Hola!';
+    }
+</pre>
+
+Once the Controller has been attached to the DOM, the `greeting` property can be data-bound to the
+template:
+
+<pre>
+    <div ng-controller="GreetingCtrl">
+      {{ greeting }}
+    </div>
+</pre>
+
+**NOTE**: Although Angular allows you to create Controller functions in the global scope, this is
+not recommended.  In a real application you should use the `.controller` method of your
+{@link module Angular Module} for your application as follows:
+
+<pre>
+    var myApp = angular.module('myApp',[]);
+
+    myApp.controller('GreetingCtrl', ['$scope', function($scope) {
+        $scope.greeting = 'Hola!';
+    }]);
+</pre>
+
+We have used an **inline injection annotation** to explicitly specify the dependency
+of the Controller on the `$scope` service provided by Angular. See the guide on 
+{@link http://docs.angularjs.org/guide/di Dependency Injection} for more information.

-When a controller function is applied to an angular scope object, the `this` of the controller
-function becomes the scope of the angular scope object, so any assignment to `this` within the
-controller function happens on the angular scope object.

 # Adding Behavior to a Scope Object

-Behavior on an angular scope object is in the form of scope method properties available to the
-template/view. This behavior interacts with and modifies the application model.
+In order to react to events or execute computation in the view we must provide behavior to the
+scope. We add behavior the scope by attaching methods to the `$scope` object.  These methods are
+then available to be called from the template/view.
+
+The following example uses a Controller to add a method to the scope, which doubles a number:
+
+<pre>
+    var myApp = angular.module('myApp',[]);
+
+    myApp.controller('DoubleCtrl', ['$scope', function($scope) {
+        $scope.double = function(value) { return value * 2; };
+    }]);
+</pre>
+
+Once the Controller has been attached to the DOM, the `double` method can be invoked in an Angular
+expression in the template:
+
+<pre>
+    <div ng-controller="DoubleCtrl">
+      Two times <input ng-model="num"> equals {{ double(num) }}
+    </div>
+</pre>

 As discussed in the {@link dev_guide.mvc.understanding_model Model} section of this guide, any
-objects (or primitives) assigned to the scope become model properties. Any functions assigned to
-the scope, along with any prototype methods of the controller type, become functions available in
-the template/view, and can be invoked via angular expressions and `ng-` event handlers (e.g. {@link
-api/angular.module.ng.$compileProvider.directive.ng-click ng-click}). These controller methods are always evaluated within the
-context of the angular scope object that the controller function was applied to (which means that
-the `this` keyword of any controller method is always bound to the scope that the controller
-augments). This is how the second task of adding behavior to the scope is accomplished.
-
+objects (or primitives) assigned to the scope become model properties. Any methods assigned to
+the scope are available in the template/view, and can be invoked via angular expressions
+and `ng` event handler directives (e.g. {@link api/ng.directive:ngClick ngClick}).

 # Using Controllers Correctly

-In general, a controller shouldn't try to do too much. It should contain only the business logic
+In general, a Controller shouldn't try to do too much. It should contain only the business logic
 needed for a single view.

-The most common way to keep controllers slim is by encapsulating work that doesn't belong to
-controllers into services and then using these services in controllers via dependency injection.
-This is discussed in the {@link dev_guide.di Dependency Injection} {@link dev_guide.services
+The most common way to keep Controllers slim is by encapsulating work that doesn't belong to
+controllers into services and then using these services in Controllers via dependency injection.
+This is discussed in the {@link di Dependency Injection} {@link dev_guide.services
 Services} sections of this guide.

-Do not use controllers for:
+Do not use Controllers for:

 - Any kind of DOM manipulation — Controllers should contain only business logic. DOM
-manipulation—the presentation logic of an application—is well known for being hard to test.
-Putting any presentation logic into controllers significantly affects testability of the business
-logic. Angular offers {@link dev_guide.templates.databinding} for automatic DOM manipulation. If
+manipulation (the presentation logic of an application) is well known for being hard to test.
+Putting any presentation logic into Controllers significantly affects testability of the business
+logic. Angular offers {@link dev_guide.templates.databinding databinding} for automatic DOM manipulation. If
 you have to perform your own manual DOM manipulation, encapsulate the presentation logic in
-{@link api/angular.module.ng.$compileProvider.directive directives}.
- Input formatting — Use {@link dev_guide.forms angular form controls} instead.
+{@link guide/directive directives}.
+- Input formatting — Use {@link forms angular form controls} instead.
 - Output filtering — Use {@link dev_guide.templates.filters angular filters} instead.
- Run stateless or stateful code shared across controllers — Use {@link dev_guide.services angular
+- Sharing stateless or stateful code across Controllers — Use {@link dev_guide.services angular
 services} instead.
- Instantiate or manage the life-cycle of other components (for example, to create service
-instances).
+- Managing the life-cycle of other components (for example, to create service instances).


 # Associating Controllers with Angular Scope Objects

-You can associate controllers with scope objects explicitly via the {@link api/angular.module.ng.$rootScope.Scope#$new
-scope.$new} api or implicitly via the {@link api/angular.module.ng.$compileProvider.directive.ng-controller ng-controller
-directive} or {@link api/angular.module.ng.$route $route service}.
+You can associate controllers with scope objects implicitly via the {@link api/ng.directive:ngController ngController
+directive} or {@link api/ng.$route $route service}.


-## Controller Constructor and Methods Example
+## Simple Spicy Controller Example

-To illustrate how the controller component works in angular, let's create a little app with the
+To illustrate further how Controller components work in Angular, let's create a little app with the
 following components:

 - A {@link dev_guide.templates template} with two buttons and a simple message
 - A model consisting of a string named `spice`
- A controller with two functions that set the value of `spice`
+- A Controller with two functions that set the value of `spice`

 The message in our template contains a binding to the `spice` model, which by default is set to the
 string "very". Depending on which button is clicked, the `spice` model is set to `chili` or
 `jalapeño`, and the message is automatically updated by data-binding.

+<doc:example module="spicyApp1">
+  <doc:source>
+    <div ng-app="spicyApp1" ng-controller="SpicyCtrl">
+     <button ng-click="chiliSpicy()">Chili</button>
+     <button ng-click="jalapenoSpicy()">Jalapeño</button>
+     <p>The food is {{spice}} spicy!</p>
+    </div>
+    <script>
+      var myApp = angular.module('spicyApp1', []);

-## A Spicy Controller Example
-
-<pre>
-<body ng-controller="SpicyCtrl">
- <button ng-click="chiliSpicy()">Chili</button>
- <button ng-click="jalapenoSpicy()">Jalapeño</button>
- <p>The food is {{spice}} spicy!</p>
-</body>
-
-function SpicyCtrl($scope) {
- $scope.spice = 'very';
- $scope.chiliSpicy = function() {
-   this.spice = 'chili';
- }
-}
-
-SpicyCtrl.prototype.jalapenoSpicy = function() {
- this.spice = 'jalapeño';
-}
-</pre>
+      myApp.controller('SpicyCtrl', ['$scope', function($scope){
+          $scope.spicy = 'very';
+          
+          $scope.chiliSpicy = function() {
+              $scope.spice = 'chili';
+          };
+          
+          $scope.jalapenoSpicy = function() {
+              $scope.spice = 'jalapeño';
+          };
+      }]);
+    </script>
+  </doc:source>
+</doc:example>

 Things to notice in the example above:

 - The `ng-controller` directive is used to (implicitly) create a scope for our template, and the
-scope is augmented (managed) by the `SpicyCtrl` controller.
+scope is augmented (managed) by the `SpicyCtrl` Controller.
 - `SpicyCtrl` is just a plain JavaScript function. As an (optional) naming convention the name
 starts with capital letter and ends with "Ctrl" or "Controller".
- The JavaScript keyword `this` in the `SpicyCtrl` function is bound to the scope that the
-controller augments.
- Assigning a property to `this` creates or updates the model.
- Controller methods can be created through direct assignment to scope (the `chiliSpicy` method) or
-as prototype methods of the controller constructor function(the `jalapenoSpicy` method)
- Both controller methods are available in the template (for the `body` element and and its
-children).
+- Assigning a property to `$scope` creates or updates the model.
+- Controller methods can be created through direct assignment to scope (see the `chiliSpicy` method)
+- The Controller methods and properties are available in the template (for the `<div>` element and
+and its children).
+
+## Spicy Arguments Example

 Controller methods can also take arguments, as demonstrated in the following variation of the
 previous example.

-## Controller Method Arguments Example
+<doc:example module="spicyApp2">
+  <doc:source>
+  <div ng-app="spicyApp2" ng-controller="SpicyCtrl">
+   <input ng-model="customSpice">
+   <button ng-click="spicy('chili')">Chili</button>
+   <button ng-click="spicy(customSpice)">Custom spice</button>
+   <p>The food is {{spice}} spicy!</p>
+  </div>
+  <script>
+    var myApp = angular.module('spicyApp2', []);

-<pre>
-<body ng-controller="SpicyCtrl">
- <input ng-model="customSpice" value="wasabi">
- <button ng-click="spicy('chili')">Chili</button>
- <button ng-click="spicy(customSpice)">Custom spice</button>
- <p>The food is {{spice}} spicy!</p>
-</body>
+    myApp.controller('SpicyCtrl', ['$scope', function($scope){
+        $scope.customSpice = "wasabi";
+        $scope.spice = 'very';
+        
+        $scope.spicy = function(spice){
+            $scope.spice = spice;
+        };
+    }]);
+  </script>
+</doc:source>
+</doc:example>

-function SpicyCtrl($scope) {
- $scope.spice = 'very';
- $scope.spicy = function(spice) {
-   this.spice = spice;
- }
-}
-</pre>
-
-Notice that the `SpicyCtrl` controller now defines just one method called `spicy`, which takes one
-argument called `spice`. The template then refers to this controller method and passes in a string
+Notice that the `SpicyCtrl` Controller now defines just one method called `spicy`, which takes one
+argument called `spice`. The template then refers to this Controller method and passes in a string
 constant `'chili'` in the binding for the first button and a model property `spice` (bound to an
 input box) in the second button.

+## Scope Inheritance Example

-## Controller Inheritance Example
+It is common to attach Controllers at different levels of the DOM hierarchy.  Since the 
+{@link api/ng.directive:ngController ng-controller} directive creates a new child scope, we get a
+hierarchy of scopes that inherit from each other.  The `$scope` that each Controller receives will
+have access to properties and methods defined by Controllers higher up the hierarchy.
+See {@link https://github.com/angular/angular.js/wiki/Understanding-Scopes Understanding Scopes} for
+more information about scope inheritance.

-Controller inheritance in angular is based on {@link api/angular.module.ng.$rootScope.Scope Scope} inheritance. Let's
-have a look at an example:
+<doc:example module="scopeInheritance">
+  <doc:source>
+    <div ng-app="scopeInheritance" class="spicy">
+      <div ng-controller="MainCtrl">
+        <p>Good {{timeOfDay}}, {{name}}!</p>

-<pre>
-<body ng-controller="MainCtrl">
- <p>Good {{timeOfDay}}, {{name}}!</p>
- <div ng-controller="ChildCtrl">
-   <p>Good {{timeOfDay}}, {{name}}!</p>
-   <p ng-controller="BabyCtrl">Good {{timeOfDay}}, {{name}}!</p>
-</body>
+        <div ng-controller="ChildCtrl">
+          <p>Good {{timeOfDay}}, {{name}}!</p>

-function MainCtrl($scope) {
- $scope.timeOfDay = 'morning';
- $scope.name = 'Nikki';
-}
+          <div ng-controller="BabyCtrl">
+            <p>Good {{timeOfDay}}, {{name}}!</p>
+          </div>
+        </div>
+      </div>
+    </div>
+    <style>
+      div.spicy div {
+        padding: 10px;
+        border: solid 2px blue;
+      }
+    </style>
+    <script>
+      var myApp = angular.module('scopeInheritance', []);
+      myApp.controller('MainCtrl', ['$scope', function($scope){
+        $scope.timeOfDay = 'morning';
+        $scope.name = 'Nikki';
+      }]);
+      myApp.controller('ChildCtrl', ['$scope', function($scope){
+        $scope.name = 'Mattie';
+      }]);
+      myApp.controller('BabyCtrl', ['$scope', function($scope){
+        $scope.timeOfDay = 'evening';
+        $scope.name = 'Gingerbreak Baby';
+      }]);
+    </script>
+  </doc:source>
+</doc:example>

-function ChildCtrl($scope) {
- $scope.name = 'Mattie';
-}
-
-function BabyCtrl($scope) {
- $scope.timeOfDay = 'evening';
- $scope.name = 'Gingerbreak Baby';
-}
-</pre>
-
-Notice how we nested three `ng-controller` directives in our template. This template construct will
-result in 4 scopes being created for our view:
+Notice how we nested three `ng-controller` directives in our template. This will result in four
+scopes being created for our view:

 - The root scope
- The `MainCtrl` scope, which contains `timeOfDay` and `name` models
- The `ChildCtrl` scope, which shadows the `name` model from the previous scope and inherits the
-`timeOfDay` model
- The `BabyCtrl` scope, which shadows both the `timeOfDay` model defined in `MainCtrl` and `name`
-model defined in the ChildCtrl
+- The `MainCtrl` scope, which contains `timeOfDay` and `name` properties
+- The `ChildCtrl` scope, which inherits the `timeOfDay` property but overrides (hides) the `name`
+property from the previous
+- The `BabyCtrl` scope, which overrides (hides) both the `timeOfDay` property defined in `MainCtrl`
+and the `name` property defined in `ChildCtrl`

-Inheritance works between controllers in the same way as it does with models. So in our previous
-examples, all of the models could be replaced with controller methods that return string values.
-
-Note: Standard prototypical inheritance between two controllers doesn't work as one might expect,
-because as we mentioned earlier, controllers are not instantiated directly by angular, but rather
-are applied to the scope object.
+Inheritance works with methods in the same way as it does with properties. So in our previous
+examples, all of the properties could be replaced with methods that return string values.


 ## Testing Controllers

-The way to test a controller depends upon how complicated the controller is.
+Although there are many ways to test a Controller, one of the best conventions, shown below,
+involves injecting the {@link api/ng.$rootScope $rootScope} and {@link api/ng.$controller $controller}:

- If your controller doesn't use DI or scope methods — create the controller with the `new`
-operator and test away. For example:
-
-Controller Function:
+**Controller Definition:**
 <pre>
-function myController() {
-   this.spices = [{"name":"pasilla", "spiciness":"mild"},
-                  {"name":"jalapeno", "spiceiness":"hot hot hot!"},
-                  {"name":"habanero", "spiceness":"LAVA HOT!!"}];
+    var myApp = angular.module('myApp',[]);

-   this.spice = "habanero";
-}
+    myApp.controller('MyController', function($scope) {
+      $scope.spices = [{"name":"pasilla", "spiciness":"mild"},
+                       {"name":"jalapeno", "spiceiness":"hot hot hot!"},
+                       {"name":"habanero", "spiceness":"LAVA HOT!!"}];
+      $scope.spice = "habanero";
+    });
 </pre>

-Controller Test:
+**Controller Test:**
 <pre>
 describe('myController function', function() {

  describe('myController', function() {
-    var ctrl;
+    var $scope;

-    beforeEach(function() {
-      ctrl = new myController();
-    });
+    beforeEach(module('myApp'));
+
+    beforeEach(inject(function($rootScope, $controller) {
+      $scope = $rootScope.$new();
+      $controller('MyController', {$scope: $scope});
+    }));

    it('should create "spices" model with 3 spices', function() {
-      expect(ctrl.spices.length).toBe(3);
+      expect($scope.spices.length).toBe(3);
    });

    it('should set the default value of spice', function() {
-      expect(ctrl.spice).toBe('habanero');
+      expect($scope.spice).toBe('habanero');
    });
  });
 });
 </pre>

- If your controller does use DI or scope methods — create a root scope, then create the controller
-in the root scope with `scope.$new(MyController)`. Test the controller using `$eval`, if necessary.
- If you need to test a nested controller that depends on its parent's state — create a root scope,
-create a parent scope, create a child scope, and test the controller using $eval if necessary.
+
+If you need to test a nested Controller you need to create the same scope hierarchy
+in your test that exists in the DOM:
+
+<pre>
+describe('state', function() {
+    var mainScope, childScope, babyScope;
+
+    beforeEach(module('myApp'));
+
+    beforeEach(inject(function($rootScope, $controller) {
+        mainScope = $rootScope.$new();
+        $controller('MainCtrl', {$scope: mainScope});
+        childScope = mainScope.$new();
+        $controller('ChildCtrl', {$scope: childScope});
+        babyScope = childScope.$new();
+        $controller('BabyCtrl', {$scope: babyScope});
+    }));
+
+    it('should have over and selected', function() {
+        expect(mainScope.timeOfDay).toBe('morning');
+        expect(mainScope.name).toBe('Nikki');
+        expect(childScope.timeOfDay).toBe('morning');
+        expect(childScope.name).toBe('Mattie');
+        expect(babyScope.timeOfDay).toBe('evening');
+        expect(babyScope.name).toBe('Gingerbreak Baby');
+    });
+});
+</pre>


 ## Related Topics
@@ -2,16 +2,16 @@
@name Developer Guide: About MVC in Angular: Understanding the Model Component
@description

-Depending on the context of the discussion in angular documentation, the term _model_ can refer to
+Depending on the context of the discussion in the Angular documentation, the term _model_ can refer to
 either a single object representing one entity (for example, a model called "phones" with its value
 being an array of phones) or the entire data model for the application (all entities).

-In angular, a model is any data that is reachable as a property of an angular {@link
-dev_guide.scopes Scope} object. The name of the property is the model identifier and the value is
+In Angular, a model is any data that is reachable as a property of an angular {@link
+scope Scope} object. The name of the property is the model identifier and the value is
 any JavaScript object (including arrays and primitives).

-The only requirement for a JavaScript object to be a model in angular is that the object must be
-referenced by an angular scope as a property of that scope object. This property reference can be
+The only requirement for a JavaScript object to be a model in Angular is that the object must be
+referenced by an Angular scope as a property of that scope object. This property reference can be
 created explicitly or implicitly.

 You can create models by explicitly creating scope properties referencing JavaScript objects in the
@@ -26,11 +26,11 @@ occurs in controllers:
             $scope.foo = 'bar';
         }

-* Use an {@link dev_guide.expressions angular expression} with an assignment operator in templates:
+* Use an {@link expression angular expression} with an assignment operator in templates:

-         <button ng-click="{{foos='ball'}}">Click me</button>
+         <button ng-click="{{foo='bar'}}">Click me</button>

-* Use {@link api/angular.module.ng.$compileProvider.directive.ng-init ng-init directive} in templates (for toy/example apps
+* Use {@link api/ng.directive:ngInit ngInit directive} in templates (for toy/example apps
 only, not recommended for real applications):

         <body ng-init=" foo = 'bar' ">
@@ -45,18 +45,18 @@ when processing the following template constructs:
   The code above creates a model called "query" on the current scope with the value set to "fluffy
 cloud".

-* An iterator declaration in {@link api/angular.module.ng.$compileProvider.directive.ng-repeat ng-repeater}:
+* An iterator declaration in {@link api/ng.directive:ngRepeat ngRepeater}:

         <p ng-repeat="phone in phones"></p>

   The code above creates one child scope for each item in the "phones" array and creates a "phone"
 object (model) on each of these scopes with its value set to the value of "phone" in the array.

-In angular, a JavaScript object stops being a model when:
+In Angular, a JavaScript object stops being a model when:

-* No angular scope contains a property that references the object.
+* No Angular scope contains a property that references the object.

-* All angular scopes that contain a property referencing the object become stale and eligible for
+* All Angular scopes that contain a property referencing the object become stale and eligible for
 garbage collection.

 The following illustration shows a simple data model created implicitly from a simple template:
@@ -2,15 +2,15 @@
@name Developer Guide: About MVC in Angular: Understanding the View Component
@description

-In angular, the view is the DOM loaded and rendered in the browser, after angular has transformed
+In Angular, the view is the DOM loaded and rendered in the browser, after Angular has transformed
 the DOM based on information in the template, controller and model.

 <img src="img/guide/about_view_final.png">

-In the angular implementation of MVC, the view has knowledge of both the model and the controller.
+In the Angular implementation of MVC, the view has knowledge of both the model and the controller.
 The view knows about the model where two-way data-binding occurs. The view has knowledge of the
-controller through angular directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng-controller
-ng-controller} and {@link api/angular.module.ng.$compileProvider.directive.ng-view ng-view}, and through bindings of this form:
+controller through Angular directives, such as {@link api/ng.directive:ngController
+ngController} and {@link api/ng.directive:ngView ngView}, and through bindings of this form:
 `{{someControllerFunction()}}`. In these ways, the view can call functions in an associated
 controller function.

@@ -1,236 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Overview
-@description
-
-
-# What Is Angular?
-
-The short answer: angular is a new, powerful, client-side technology that makes it much easier for
-you to create dynamic web sites and complex web apps, all without leaving the comfort of your HTML
-/ JavaScript home.
-
-The long answer: it depends on where you're coming from...
-
-* If you're a web designer, you might perceive angular to be a sweet {@link dev_guide.templates
-templating} system, that doesn't get in your way and provides you with lots of nice built-ins that
-make it easier to do what you want to do.
-
-* If you're a web developer, you might be thrilled that angular functions as an excellent web
-framework, one that assists you all the way through the development cycle.
-
-* If you want to go deeper, you can immerse yourself in angular's extensible  HTML {@link
-dev_guide.compiler compiler} that runs in your browser. The angular compiler teaches your browser
-new tricks.
-
-Angular is not just a templating system, but you can create fantastic templates with it. Angular is
-not just a web framework, but it features a very nice framework. Angular is not just an extensible
-HTML compiler, but the compiler is at the core of Angular. Angular includes all of these
-components, along with others. Angular is far greater than the sum of its parts. It is a new,
-better way to develop web applications!
-
-
-## An Introductory Angular Example
-
-Let's say that you are a web designer, and you've spent many thous — erm, hundreds of hours
-designing web sites. But at this point, the thought of manipulating the DOM, writing listeners and
-input validators, all just to implement a simple form?  No. You either don't want to go there in
-the first place or you've been there and the thrill is gone.
-
-So look over the following simple example written using angular.  Note that it features only the
-templating aspect of angular, but this should suffice for now to quickly demonstrate how much
-easier a web developer's life can if they're using angular:
-
-<doc:example>
-<doc:source>
- <script>
-   function InvoiceCntl($scope) {
-     $scope.qty = 1;
-     $scope.cost = 19.95;
-   }
- </script>
- <div ng-controller="InvoiceCntl">
-   <b>Invoice:</b>
-   <br />
-   <br />
-   <table>
-    <tr><td> </td><td> </td>
-    <tr><td>Quantity</td><td>Cost</td></tr>
-    <tr>
-      <td><input type="integer" min="0" ng-model="qty" required ></td>
-      <td><input type="number" ng-model="cost" required ></td>
-    </tr>
-   </table>
-   <hr />
-   <b>Total:</b> {{qty * cost | currency}}
- </div>
-</doc:source>
-<!--
-<doc:scenario>
- it('should show of angular binding', function() {
-   expect(binding('qty * cost')).toEqual('$19.95');
-   input('qty').enter('2');
-   input('cost').enter('5.00');
-   expect(binding('qty * cost')).toEqual('$10.00');
- });
-</doc:scenario>
-->
-</doc:example>
-
-Try out the Live Preview above, and then let's walk through the example and describe what's going
-on.
-
-In the `<html>` tag we specify that this is an angular application with the `ng-app` directive.
-The `ng-app' will cause the angular to {@link dev_guide.bootstrap auto initialize} your application.
-
-        <html ng-app>
-
-We load the angular using the  `<script>` tag:
-
-    <script src="http://code.angularjs.org/angular-?.?.?.min.js"></script>
-
-From the `ng-model` attribute of the `<input>` tags, angular automatically sets up two-way data
-binding, and we also demonstrate some easy input validation:
-
-        Quantity: <input type="integer" min="0" ng-model="qty" required >
-        Cost: <input type="number" ng-model="cost" required >
-
-These input widgets look normal enough, but consider these points:
-
-* When this page loaded, angular bound the names of the input widgets (`qty` and `cost`) to
-variables of the same name. Think of those variables as the "Model" component of the
-Model-View-Controller design pattern.
-* Note the angular/HTML widget, {@link api/angular.module.ng.$compileProvider.directive.input input}.
-You may have noticed that when you enter invalid data
-or leave the the input fields blank, the borders turn red color, and the display value disappears.
-These widgets make it easier to implement field validation than coding them in JavaScript,
-no?  Yes.
-
-And finally, the mysterious `{{ double curly braces }}`:
-
-         Total: {{qty * cost | currency}}
-
-This notation, `{{ _expression_ }}`, is a bit of built-in angular binding markup, a shortcut for
-displaying data to the user. The expression within curly braces is monitored and its evaluated value
-is updated into the view by angular's template compiler. Alternatively, one could use angular's
-{@link api/angular.module.ng.$compileProvider.directive.ng-bind ng-bind}) directive. The expression
-itself can be a combination of both an expression and a {@link dev_guide.templates.filters filter}:
-`{{ expression | filter }}`. Angular provides filters for formatting display data.
-
-In the example above, the expression in double-curly braces directs angular to, "Bind the data we
-got from the input widgets to the display, multiply them together, and format the resulting number
-into output that looks like money."
-
-
-# The Angular Philosophy
-
-Angular is built around the belief that declarative code is better than imperative when it comes to
-building UIs and wiring software components together, while imperative code is excellent for
-expressing business logic.
-
-Not to put too fine a point on it, but if you wanted to add a new label to your application, you
-could do so by simply adding text to the HTML template, saving the code, and refreshing your
-browser:
-
-<pre>
-<span class="label">Hello</span>
-</pre>
-
-Or, as in programmatic systems (like {@link http://code.google.com/webtoolkit/ GWT}), you would
-have to write the code and then run the code like this:
-
-<pre>
-var label = new Label();
-label.setText('Hello');
-label.setClass('label');
-parent.addChild(label);
-</pre>
-
-That's one line of markup versus four times as much code.
-
-
-## More Angular Philosophy
-
-* It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves
-the testability of the code.
-* It is a really, _really_ good idea to regard app testing as equal in importance to app writing.
-Testing difficulty is dramatically affected by the way the code is structured.
-* It is an excellent idea to decouple the client side of an app from the server side. This allows
-development work to progress in parallel, and allows for reuse of both sides.
-* It is very helpful indeed if the framework guides developers through the entire journey of
-building an app: from designing the UI, through writing the business logic, to testing.
-* It is always good to make common tasks trivial and difficult tasks possible.
-
-Now that we're homing in on what angular is, perhaps now would be a good time to list a few things
-that angular is not:
-
-* It's not a Library. You don't just call its functions, although it does provide you with some
-utility APIs.
-* It's not a DOM Manipulation Library. Angular uses jQuery to manipulate the DOM behind the scenes,
-rather than give you functions to manipulate the DOM yourself.
-* It's not a Widget Library. There are lots of existing widget libraries that you can integrate
-with angular.
-* It's not "Just Another Templating System". A part of angular is a templating system. The
-templating subsystem of angular is different from the traditional approach for these reasons:
-    * It Uses HTML/CSS syntax: This makes it easy to read and can be edited with existing HTML/CSS
-authoring tools.
-    * It Extends HTML vocabulary: Angular allows you to create new HTML tags, which expand into
-dynamic UI components.
-    * It Executes in the browser: Removes the round trip to the server for many operations and
-creates instant feedback for users as well as developers.
-    * It Has Bidirectional data binding: The model is the single source of truth. Programmatic
-changes to the model are automatically reflected in the view. Any changes by the user to the view
-are automatically reflected in the model.
-
-
-# Why You Want Angular
-
-Angular frees you from the following pain:
-
-* **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the
-forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It vastly
-reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see what your
-application does.
-* **Manipulating HTML DOM programatically:** Manipulating HTML DOM is a cornerstone of AJAX
-applications, but it's cumbersome and error-prone. By declaratively describing how the UI should
-change as your application state changes, you are freed from low level DOM manipulation tasks. Most
-applications written with angular never have to programatically manipulate the DOM, although you
-can if you want to.
-* **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX
-applications. The flow of marshaling data from the server to an internal object to an HTML form,
-allowing users to modify the form, validating the form, displaying validation errors, returning to
-an internal model, and then back to the server, creates a lot of boilerplate code. Angular
-eliminates almost all of this boilerplate, leaving code that describes the overall flow of the
-application rather than all of the implementation details.
-* **Writing tons of initialization code just to get started:** Typically you need to write a lot of
-plumbing just to get a basic "Hello World" AJAX app working. With angular you can bootstrap your
-app easily using services, which are auto-injected into your application in a {@link
-http://code.google.com/p/google-guice/ Guice}-like dependency-injection style. This allows you to
-get started developing features quickly. As a bonus, you get full control over the initialization
-process in automated tests.
-
-
-# Watch a Presentation About Angular
-
-Here is an early presentation on angular, but note that substantial development has occurred since
-the talk was given in July of 2010.
-
-<object width="480" height="385">
- <param name="movie" value="http://www.youtube.com/v/elvcgVSynRg&amp;hl=en_US&amp;fs=1"></param>
- <param name="allowFullScreen" value="true"></param>
- <param name="allowscriptaccess" value="always"></param>
- <embed src="http://www.youtube.com/v/elvcgVSynRg&amp;hl=en_US&amp;fs=1"
-        type="application/x-shockwave-flash" allowscriptaccess="always"
-        allowfullscreen="true" width="480" height="385"></embed>
-</object>
-
-{@link
-
-https://docs.google.com/present/edit?id=0Abz6S2TvsDWSZDQ0OWdjaF8yNTRnODczazdmZg&hl=en&authkey=CO-b7oID
-
-Presentation}
-|
-{@link
-
-https://docs.google.com/document/edit?id=1ZHVhqC0apbzPRQcgnb1Ye-bAUbNJ-IlFMyPBPCZ2cYU&hl=en&authkey=CInnwLYO
-
-Source}
@@ -1,230 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Scopes: Scope Internals
-@description
-
-## What is a scope?
-
-A scope is an execution context for {@link dev_guide.expressions expressions}. You can think of a
-scope as a JavaScript object that has an extra set of APIs for registering change listeners and for
-managing its own life cycle.  In Angular's implementation of the model-view-controller design
-pattern, a scope's properties comprise both the model and the controller methods.
-
-
-### Scope characteristics
- Scopes provide APIs ({@link api/angular.module.ng.$rootScope.Scope#$watch $watch}) to observe model mutations.
- Scopes provide APIs ({@link api/angular.module.ng.$rootScope.Scope#$apply $apply}) to propagate any model changes
-through the system into the view from outside of the "Angular realm" (controllers, services,
-Angular event handlers).
- Scopes can be nested to isolate application components while providing access to shared model
-properties. A scope (prototypically) inherits properties from its parent scope.
- In some parts of the system (such as controllers, services and directives), the scope is made
-available as `this` within the given context. (Note: This api will change before 1.0 is released.)
-
-
-### Root scope
-
-Every application has a root scope, which is the ancestor of all other scopes.
-
-### What is scope used for?
-
-{@link dev_guide.expressions Expressions} in the view are {@link api/angular.module.ng.$rootScope.Scope#$eval evaluated}
-against the current scope. When HTML DOM elements are attached to a scope, expressions in those
-elements are evaluated against the attached scope.
-
-There are two kinds of expressions:
-
- Binding expressions, which are observations of property changes. Property changes are reflected
-in the view during the {@link api/angular.module.ng.$rootScope.Scope#$digest digest cycle}.
- Action expressions, which are expressions with side effects. Typically, the side effects cause
-execution of a method in a controller in response to a user action, such as clicking on a button.
-
-
-### Scope inheritance
-
-A scope (prototypically) inherits properties from its parent scope. Since a given property may not
-reside on a child scope, if a property read does not find the property on a scope, the read will
-recursively check the parent scope, grandparent scope, etc. all the way to the root scope before
-defaulting to undefined.
-
-{@link api/angular.module.ng.$compileProvider.directive directives} associated with elements
-(ng-controller, ng-repeat, ng-include, etc.) create new child scopes that inherit properties from
-the current parent scope. Any code in Angular is free to create a new scope. Whether or not your
-code does so is an implementation detail of the directive, that is, you can decide when or if this
-happens. Inheritance typically mimics HTML DOM element nesting, but does not do so with the same
-granularity.
-
-A property write will always write to the current scope. This means that a write can hide a parent
-property within the scope it writes to, as shown in the following example.
-
-<pre>
-it('should inherit properties', inject(function($rootScope)) {
-  var root = $rootScope;
-  var child = root.$new();
-
-  root.name = 'angular';
-  expect(child.name).toEqual('angular');
-  expect(root.name).toEqual('angular');
-
-  child.name = 'super-heroic framework';
-  expect(child.name).toEqual('super-heroic framework');
-  expect(root.name).toEqual('angular');
-});
-</pre>
-
-
-### Scope life cycle
-1. **Creation**
-
-   * The root scope is created by the  {@link api/angular.module.ng.$rootScope $rootScope} service.
-   * To create a child scopes, you should call {@link api/angular.module.ng.$rootScope.Scope#$new parentScope.$new()}.
-
-2. **Watcher registration**
-
-   Watcher registration can happen at any time and on any scope (root or child) via {@link
-api/angular.module.ng.$rootScope.Scope#$watch scope.$watch()} API.
-
-3. **Model mutation**
-
-   For mutations to be properly observed, you should make them only within the execution of the
-function passed into {@link api/angular.module.ng.$rootScope.Scope#$apply scope.$apply()} call. (Angular apis do this
-implicitly, so no extra `$apply` call is needed when doing synchronous work in controllers, or
-asynchronous work with {@link api/angular.module.ng.$http $http} or {@link api/angular.module.ng.$defer
-$defer} services.
-
-4. **Mutation observation**
-
-   At the end of each `$apply` call {@link api/angular.module.ng.$rootScope.Scope#$digest $digest} cycle is started on
-the root scope, which then propagates throughout all child scopes.
-
-   During the `$digest` cycle, all `$watch-ers` expressions or functions are checked for model
-mutation and if a mutation is detected, the `$watch-er` listener is called.
-
-5. **Scope destruction**
-
-   When child scopes are no longer needed, it is the responsibility of the child scope creator to
-destroy them via {@link api/angular.module.ng.$rootScope.Scope#$destroy scope.$destroy()} API. This will stop
-propagation of `$digest` calls into the child scope and allow for memory used by the child scope
-models to be reclaimed by the garbage collector.
-
-   The root scope can't be destroyed via the `$destroy` API. Instead, it is enough to remove all
-references from your application to the scope object and garbage collector will do its magic.
-## Scopes in Angular applications
-To understand how Angular applications work, you need to understand how scopes work within an
-application. This section describes the typical life cycle of an application so you can see how
-scopes come into play throughout and get a sense of their interactions.
-### How scopes interact in applications
-
-1. At application compile time, a root scope is created and is attached to the root `<HTML>` DOM
-element.
-2. During the compilation phase, the {@link dev_guide.compiler compiler} matches {@link
-api/angular.module.ng.$compileProvider.directive directives} against the DOM template. The directives
-usually fall into one of two categories:
-   - Observing {@link api/angular.module.ng.$compileProvider.directive directives}, such as double-curly
-    expressions `{{expression}}`, register listeners using the {@link
-    api/angular.module.ng.$rootScope.Scope#$watch $watch()} method. This type of directive needs to
-    be notified whenever the expression changes so that it can update the view.
-   -  Listener directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng-click
-   ng-click}, register a listener with the DOM. When the DOM listener fires, the directive executes
-   the associated expression and updates the view using  the {@link
-   api/angular.module.ng.$rootScope.Scope#$apply $apply()} method.
-3. When an external event (such as a user action, timer or XHR) is received, the associated {@link
-dev_guide.expressions expression} must be applied to the scope through the {@link
-api/angular.module.ng.$rootScope.Scope#$apply $apply()} method so that all listeners are updated correctly.
-
-
-### Directives that create scopes
-In most cases, {@link api/angular.module.ng.$compileProvider.directive directives} and scopes interact but do not create new
-instances of scope. However, some directives, such as {@link api/angular.module.ng.$compileProvider.directive.ng-controller
-ng-controller} and {@link api/angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat}, create new child scopes using
-the {@link api/angular.module.ng.$rootScope.Scope#$new $new()} method and then attach the child scope to the
-corresponding DOM element. You can retrieve a scope for any DOM element by using an
-`angular.element(aDomElement).scope()` method call.)
-
-
-### Controllers and scopes
-Scopes and controllers interact with each other in the following situations:
-   - Controllers use scopes to expose controller methods to templates (see {@link
-api/angular.module.ng.$compileProvider.directive.ng-controller ng-controller}).
-   - Controllers define methods (behavior) that can mutate the model (properties on the scope).
-   - Controllers may register {@link api/angular.module.ng.$rootScope.Scope#$watch watches} on the model. These watches
-execute immediately after the controller behavior executes, but before the DOM gets updated.
-
-See the {@link dev_guide.mvc.understanding_controller controller docs} for more information.
-
-### Updating scope properties
-You can update a scope by calling its {@link api/angular.module.ng.$rootScope.Scope#$apply $apply()} method with an
-expression or a function as the function argument. However it is typically not necessary to do this
-explicitly. In most cases, angular intercepts all external events (such as user interactions, XHRs,
-and timers) and wraps their callbacks into the `$apply()` method call on the scope object for you
-at the right time. The only time you might need to call `$apply()` explicitly is when you create
-your own custom asynchronous widget or service.
-
-The reason it is unnecessary to call `$apply()` from within your controller functions when you use
-built-in angular widgets and services is because your controllers are typically called from within
-an `$apply()` call already.
-
-When a user inputs data, angularized widgets invoke `$apply()` on the current scope and evaluate an
-angular expression or execute a function on this scope. Afterwards `$apply` will trigger `$digest`
-call on the root scope, to propagate your changes through the entire system, which results in
-$watch-ers firing and view getting updated. Similarly, when a request to fetch data from a server
-is made and the response comes back, the data is written into the model (scope) within an $apply,
-which then pushes updates through to the view and any other dependents.
-
-A widget that creates scopes (such as {@link api/angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat}) via `$new`,
-doesn't need to worry about propagating the `$digest` call from the parent scope to child scopes.
-This happens automatically.
-
-## Scopes in unit-testing
-You can create scopes, including the root scope, in tests by having the $rootScope injected into
-your spec. This allows you to mimic the run-time environment and have full control over
-the life cycle of the scope so that you can assert correct model transitions. Since these scopes
-are created outside the normal compilation process, their life cycles must be managed by the test.
-
-### Using scopes in unit-testing
-The following example demonstrates how the scope life cycle needs to be manually triggered from
-within the unit-tests.
-
-<pre>
-  // example of a test
-  it('should trigger a watcher', inject(function($rootScope) {
-    var scope = $rootScope;
-    scope.$watch('name', function(name) {
-     scope.greeting = 'Hello ' + name + '!';
-    });
-
-    scope.name = 'angular';
-    // The watch does not fire yet since we have to manually trigger the digest phase.
-    expect(scope.greeting).toEqual(undefined);
-
-    // manually trigger digest phase from the test
-    scope.$digest();
-    expect(scope.greeting).toEqual('Hello Angular!');
-  }
-</pre>
-
-
-### Dependency injection in Tests
-
-When you find it necessary to inject your own mocks in your tests, use a scope to override the
-service instances, as shown in the following example.
-
-<pre>
-it('should allow override of providers', inject(
-  function($provide) {
-    $provide.value('$location', {mode:'I am a mock'});
-  },
-  function($location){
-    expect($location.mode).toBe('I am a mock');
-  }
-)};
-</pre>
-
-## Related Topics
-
-* {@link dev_guide.scopes Angular Scope Objects}
-* {@link dev_guide.scopes.understanding_scopes Understanding Scopes}
-
-## Related API
-
-* {@link api/angular.module.ng.$rootScope.Scope Angular Scope API}
-
@@ -1,35 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Scopes
-@description
-
-
-An Angular scope is a JavaScript object with additional APIs useful for watching property changes,
-Angular scope is the model in Model-View-Controller paradigm. Instances of scope serve as the
-context within which all {@link dev_guide.expressions expressions} get evaluated.
-
-You can think of Angular scope objects as the medium through which the model, view, and controller
-communicate. Scopes are linked during the compilation process with the view. This linkage provides
-the contexts in which Angular creates data-bindings between the model and the view.
-
-In addition to providing the context in which data is evaluated, Angular scope objects watch for
-model changes. The scope objects also notify all components interested in any model changes (for
-example, functions registered through {@link api/angular.module.ng.$rootScope.Scope#$watch $watch}, bindings created by
-{@link api/angular.module.ng.$compileProvider.directive.ng-bind ng-bind}, or HTML input elements).
-
-Angular scope objects:
-
-* Link the model, controller and view template together.
-* Provide the mechanism to watch for model changes ({@link api/angular.module.ng.$rootScope.Scope#$watch $watch}).
-* Apply model changes to the system ({@link api/angular.module.ng.$rootScope.Scope#$apply $apply}).
-* Provide the context in which expressions are evaluated ({@link api/angular.module.ng.$rootScope.Scope#$eval $eval}).
-
-
-## Related Topics
-
-* {@link dev_guide.scopes.understanding_scopes Understanding Scopes}
-* {@link dev_guide.scopes.internals Scopes Internals}
-
-## Related API
-
-* {@link api/angular.module.ng.$rootScope.Scope Angular Scope API}
-
@@ -1,66 +0,0 @@
-@ngdoc overview
-@name Developer Guide: Scopes: Understanding Scopes
-@description
-
-Angular automatically creates a root scope during initialization, and attaches it to the page's
-root DOM element (usually `<html>`). The root scope object, along with any of its child scope
-objects, serves as the infrastructure on which your data model is built. The data model (JavaScript
-objects, arrays, or primitives) is attached to angular scope properties. Angular binds the property
-values to the DOM where bindings are specified in the template. Angular attaches any controller
-functions you have created to their respective scope objects.
-
-<img src="img/guide/simple_scope_final.png">
-
-Angular scopes can be nested, so a child scope has a parent scope upstream in the DOM.  When you
-display an angular expression in the view, angular walks the DOM tree looking in the closest
-attached scope object for the specified data. If it doesn't find the data in the closest attached
-scope, it looks further up the scope hierarchy until it finds the data.
-
-A child scope object inherits properties from its parents. For example, in the following snippet of
-code, observe how the value of `name` changes, based on the HTML element it is displayed in:
-
-<doc:example>
-<doc:source>
- <ul ng-init="name='Hank'; names=['Igor', 'Misko', 'Gail', 'Kai']">
-   <li ng-repeat="name in names">
-           Name = {{name}}!
-   </li>
- </ul>
- <pre>Name={{name}}</pre>
-</doc:source>
-<doc:scenario>
-   it('should override the name property', function() {
-     expect(using('.doc-example-live').repeater('li').row(0)).
-       toEqual(['Igor']);
-     expect(using('.doc-example-live').repeater('li').row(1)).
-       toEqual(['Misko']);
-
-     expect(using('.doc-example-live').repeater('li').row(2)).
-       toEqual(['Gail']);
-     expect(using('.doc-example-live').repeater('li').row(3)).
-       toEqual(['Kai']);
-     expect(using('.doc-example-live').element('pre').text()).
-       toBe('Name=Hank');
-   });
-</doc:scenario>
-</doc:example>
-
-The angular {@link api/angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} directive creates a new scope for each
-element that it repeats (in this example the elements are list items). In the `<ul>` element, we
-initialized `name` to "Hank", and we created an array called `names` to use as the data source for
-the list items. In each `<li>` element, `name` is overridden. Outside of the `<li>` repeater, the
-original value of `name` is displayed.
-
-The following illustration shows the DOM and angular scopes for the example above:
-
-<img src="img/guide/dom_scope_final.png">
-
-
-## Related Topics
-
-* {@link dev_guide.scopes Angular Scope Objects}
-* {@link dev_guide.scopes.internals Scopes Internals}
-
-## Related API
-
-* {@link api/angular.module.ng.$rootScope.Scope Angular Scope API}
@@ -14,22 +14,22 @@ changes to $location are reflected into the browser address bar.
 - Exposes the current URL in the browser address bar, so you can
  - Watch and observe the URL.
  - Change the URL.
- Synchronizes the URL with the browser when the user
-  - Changes the address bar.
-  - Clicks the back or forward button (or clicks a History link).
-  - Clicks on a link.
+- Maintains synchronization between itself and the browser's URL when the user
+  - Changes the address in the browser's address bar.
+  - Clicks the back or forward button in the browser (or clicks a History link).
+  - Clicks on a link in the page.
 - Represents the URL object as a set of methods (protocol, host, port, path, search, hash).


 ## Comparing $location to window.location

-<table>
+<table class="table">
 <thead>

  <tr>
-    <td class="empty-corner-lt"></td>
-    <td>window.location</td>
-    <td>$location service</td>
+    <th class="empty-corner-lt"></th>
+    <th>window.location</th>
+    <th>$location service</th>
  </tr>

 </thead>
@@ -73,10 +73,9 @@ Any time your application needs to react to a change in the current URL or if yo
 the current URL in the browser.

 ## What does it not do?
-Does not cause a full page reload when the browser URL is changed. To reload the page after
+It does not cause a full page reload when the browser URL is changed. To reload the page after
 changing the URL, use the lower-level API, `$window.location.href`.

-
 # General overview of the API

 The `$location` service can behave differently, depending on the configuration that was provided to
@@ -89,7 +88,7 @@ setter methods that allow you to get or change the current URL in the browser.
 ## $location service configuration

 To configure the `$location` service, retrieve the
-{@link api/angular.module.ng.$locationProvider $locationProvider} and set the parameters as follows:
+{@link api/ng.$locationProvider $locationProvider} and set the parameters as follows:


 - **html5Mode(mode)**: {boolean}<br />
@@ -99,7 +98,7 @@ To configure the `$location` service, retrieve the

 - **hashPrefix(prefix)**: {string}<br />
  prefix used for Hashbang URLs (used in Hashbang mode or in legacy browser in Html5 mode)<br />
-  default: `'!'`
+  default: `""`

 ### Example configuration
 <pre>
@@ -122,6 +121,8 @@ All of the setter methods return the same `$location` object to allow chaining.
 change multiple segments in one go, chain setters like this:
 <pre>$location.path('/newValue').search({key: value});</pre>

+## Replace method
+
 There is a special `replace` method which can be used to tell the $location service that the next
 time the $location service is synced with the browser, the last history record should be replaced
 instead of creating a new one. This is useful when you want to implement redirection, which would
@@ -133,12 +134,12 @@ current URL without creating a new browser history record you can call:
  // or you can chain these as: $location.path('/someNewPath').replace();
 </pre>

-Note that the setters don't update `window.location` immediately. Instead, `$location` service is
-aware of the {@link api/angular.module.ng.$rootScope.Scope scope} life-cycle and coalesces multiple `$location`
+Note that the setters don't update `window.location` immediately. Instead, the `$location` service is
+aware of the {@link api/ng.$rootScope.Scope scope} life-cycle and coalesces multiple `$location`
 mutations into one "commit" to the `window.location` object during the scope `$digest` phase. Since
 multiple changes to the $location's state will be pushed to the browser as a single change, it's
 enough to call the `replace()` method just once to make the entire "commit" a replace operation
-rather than addition to the browser history. Once the browser is updated, the $location service
+rather than an addition to the browser history. Once the browser is updated, the $location service
 resets the flag set by `replace()` method and future mutations will create new history records,
 unless `replace()` is called again.

@@ -165,13 +166,13 @@ facilitate the browser URL change and history management.

 <img src="img/guide/hashbang_vs_regular_url.jpg">

-<table>
+<table class="table">
 <thead>

  <tr>
-    <td class="empty-corner-lt"></td>
-    <td>Hashbang mode</td>
-    <td>HTML5 mode</td>
+    <th class="empty-corner-lt"></th>
+    <th>Hashbang mode</th>
+    <th>HTML5 mode</th>
  </tr>

 </thead>
@@ -212,8 +213,8 @@ In this mode, `$location` uses Hashbang URLs in all browsers.
 <pre>
 it('should show example', inject(
  function($locationProvider) {
-    $locationProvider.html5mode = false;
-    $locationProvider.hashPrefix = '!';
+    $locationProvider.html5Mode(false);
+    $locationProvider.hashPrefix('!');
  },
  function($location) {
    // open http://host.com/base/index.html#!/a
@@ -261,8 +262,8 @@ having to worry about whether the browser displaying your app supports the histo
 <pre>
 it('should show example', inject(
  function($locationProvider) {
-    $locationProvider.html5mode = true;
-    $locationProvider.hashPrefix = '!';
+    $locationProvider.html5Mode(true);
+    $locationProvider.hashPrefix('!');
  },
  function($location) {
    // in browser with HTML5 history support:
@@ -304,8 +305,8 @@ history API  or not; the `$location` service makes this transparent to you.

 ### Html link rewriting

-When you use the history API mode, you will need different links in different browser, but all you
-have to do is specify regular URL links, such as: `&lt;a href="/some?foo=bar"&gt;link&lt;/a&gt;`
+When you use HTML5 history API mode, you will need different links in different browsers, but all you
+have to do is specify regular URL links, such as: `<a href="/some?foo=bar">link</a>`

 When a user clicks on this link,

@@ -316,12 +317,21 @@ When a user clicks on this link,
 In cases like the following, links are not rewritten; instead, the browser will perform a full page
 reload to the original link.

- Links with an `ng-ext-link` directive<br />
-  Example: `<a href="/ext/link?a=b" ng-ext-link>link</a>`
- Links that contain `target="_blank"`<br />
-  Example: `<a href="/ext/link?a=b" target="_blank">link</a>`
- Absolute links that go to a different domain<br />
+- Links that contain `target` element<br>
+  Example: `<a href="/ext/link?a=b" target="_self">link</a>`
+- Absolute links that go to a different domain<br>
  Example: `<a href="http://angularjs.org/">link</a>`
+- Links starting with '/' that lead to a different base path when base is defined<br>
+  Example: `<a href="/not-my-base/link">link</a>`
+  
+When running Angular in the root of a domain, along side perhaps a normal application in the same
+directory, the "otherwise" route handler will try to handle all the URLs, including ones that map
+to static files.
+
+To prevent this, you can set your base href for the app to `<base href=".">` and then prefix links
+to URLs that should be handled with `.`. Now, links to locations, which are not to be routed by Angular,
+are not prefixed with `.` and will not be intercepted by the `otherwise` rule in your `$routeProvider`.
+

 ### Server side

@@ -330,22 +340,24 @@ to entry point of your application (e.g. index.html)

 ### Crawling your app

-If you want your AJAX application to be indexed by web crawlers, you rill need to add the following
+If you want your AJAX application to be indexed by web crawlers, you will need to add the following
 meta tag to the HEAD section of your document:
 <pre><meta name="fragment" content="!" /></pre>

-This statement causes a crawler to request links with empty `_escaped_fragment_` parameter so that
+This statement causes a crawler to request links with an empty `_escaped_fragment_` parameter so that
 your server can recognize the crawler and serve it HTML snapshots. For more information about this
 technique, see {@link http://code.google.com/web/ajaxcrawling/docs/specification.html Making AJAX
 Applications Crawlable}.

 ### Relative links

-Be sure to check all relative links, images, scripts etc. You must use an absolute path because the
-path is going to be rewritten. You can use `<base href="" />` tag as well.
+Be sure to check all relative links, images, scripts etc. You must either specify the url base in
+the head of your main html file (`<base href="/my-base">`) or you must use absolute urls
+(starting with `/`) everywhere because relative urls will be resolved to absolute urls using the
+initial absolute url of the document, which is often different from the root of the application.

 Running Angular apps with the History API enabled from document root is strongly encouraged as it
-takes care of all relative link issues. **Otherwise you have to specify &lt;base href="" /&gt; !**
+takes care of all relative link issues.

 ### Sending links among different browsers

@@ -372,34 +384,34 @@ In this examples we use `<base href="/base/index.html" />`
 <div ng-non-bindable class="html5-hashbang-example">
  <div id="html5-mode" ng-controller="Html5Cntl">
    <h3>Browser with History API</h3>
-    <ng-address-bar browser="html5"></ng-address-bar><br /><br />
-    $location.protocol() = {{$location.protocol()}}<br />
-    $location.host() = {{$location.host()}}<br />
-    $location.port() = {{$location.port()}}<br />
-    $location.path() = {{$location.path()}}<br />
-    $location.search() = {{$location.search()}}<br />
-    $location.hash() = {{$location.hash()}}<br />
-    <a href="/base/first?a=b">/base/first?a=b</a> |
-    <a href="sec/ond?flag#hash">sec/ond?flag#hash</a> |
-    <a href="/base/another?search" ng-ext-link>external</a>
+    <div ng-address-bar browser="html5"></div><br><br>
+    $location.protocol() = {{$location.protocol()}}<br>
+    $location.host() = {{$location.host()}}<br>
+    $location.port() = {{$location.port()}}<br>
+    $location.path() = {{$location.path()}}<br>
+    $location.search() = {{$location.search()}}<br>
+    $location.hash() = {{$location.hash()}}<br>
+    <a href="http://www.host.com/base/first?a=b">/base/first?a=b</a> |
+    <a href="http://www.host.com/base/sec/ond?flag#hash">sec/ond?flag#hash</a> |
+    <a href="/other-base/another?search">external</a>
  </div>

  <div id="hashbang-mode" ng-controller="HashbangCntl">
    <h3>Browser without History API</h3>
-    <ng-address-bar browser="hashbang"></ng-address-bar><br /><br />
-    $location.protocol() = {{$location.protocol()}}<br />
-    $location.host() = {{$location.host()}}<br />
-    $location.port() = {{$location.port()}}<br />
-    $location.path() = {{$location.path()}}<br />
-    $location.search() = {{$location.search()}}<br />
-    $location.hash() = {{$location.hash()}}<br />
-    <a href="/base/first?a=b">/base/first?a=b</a> |
-    <a href="sec/ond?flag#hash">sec/ond?flag#hash</a> |
-    <a href="/base/another?search" ng-ext-link>external</a>
+    <div ng-address-bar browser="hashbang"></div><br><br>
+    $location.protocol() = {{$location.protocol()}}<br>
+    $location.host() = {{$location.host()}}<br>
+    $location.port() = {{$location.port()}}<br>
+    $location.path() = {{$location.path()}}<br>
+    $location.search() = {{$location.search()}}<br>
+    $location.hash() = {{$location.hash()}}<br>
+    <a href="http://www.host.com/base/first?a=b">/base/first?a=b</a> |
+    <a href="http://www.host.com/base/sec/ond?flag#hash">sec/ond?flag#hash</a> |
+    <a href="/other-base/another?search">external</a>
  </div>
 </div>

-<script type="text/javascript">
+<script>
  function FakeBrowser(initUrl, baseHref) {
    this.onUrlChange = function(fn) {
      this.urlChange = fn;
@@ -417,7 +429,6 @@ In this examples we use `<base href="/base/index.html" />`
      return baseHref;
    };

-    this.hover = angular.noop;
    this.notifyWhenOutstandingRequests = angular.noop;
  }

@@ -426,20 +437,19 @@ In this examples we use `<base href="/base/index.html" />`
    hashbang: new FakeBrowser('http://www.host.com/base/index.html#!/path?a=b#h', '/base/index.html')
  };

-  function Html5Cntl($location) {
-    this.$location = $location;
+  function Html5Cntl($scope, $location) {
+    $scope.$location = $location;
  }

-  function HashbangCntl($location) {
-    this.$location = $location;
+  function HashbangCntl($scope, $location) {
+    $scope.$location = $location;
  }

  function initEnv(name) {
    var root = angular.element(document.getElementById(name + '-mode'));
    angular.bootstrap(root, [function($compileProvider, $locationProvider, $provide){
-      $locationProvider.html5Mode = true;
-      $locationProvider.hashPrefix = '!';
-      
+      $locationProvider.html5Mode(true).hashPrefix('!');
+
      $provide.value('$browser', browsers[name]);
      $provide.value('$document', root);
      $provide.value('$sniffer', {history: name == 'html5'});
@@ -447,7 +457,7 @@ In this examples we use `<base href="/base/index.html" />`
      $compileProvider.directive('ngAddressBar', function() {
        return function(scope, elm, attrs) {
          var browser = browsers[attrs.browser],
-              input = angular.element('<input type="text" />').val(browser.url()),
+              input = angular.element('<input type="text">').val(browser.url()),
              delay;

          input.bind('keypress keyup keydown', function() {
@@ -488,11 +498,11 @@ In this examples we use `<base href="/base/index.html" />`

 The `$location` service allows you to change only the URL; it does not allow you to reload the
 page. When you need to change the URL and reload the page or navigate to a different page, please
-use a lower level API, {@link api/angular.module.ng.$window $window.location.href}.
+use a lower level API, {@link api/ng.$window $window.location.href}.

 ## Using $location outside of the scope life-cycle

-`$location` knows about Angular's {@link api/angular.module.ng.$rootScope.Scope scope} life-cycle. When a URL changes in
+`$location` knows about Angular's {@link api/ng.$rootScope.Scope scope} life-cycle. When a URL changes in
 the browser it updates the `$location` and calls `$apply` so that all $watchers / $observers are
 notified.
 When you change the `$location` inside the `$digest` phase everything is ok; `$location` will
@@ -512,7 +522,7 @@ hashPrefix.
 # Testing with the $location service

 When using `$location` service during testing, you are outside of the angular's {@link
-api/angular.module.ng.$rootScope.Scope scope} life-cycle. This means it's your responsibility to call `scope.$apply()`.
+api/ng.$rootScope.Scope scope} life-cycle. This means it's your responsibility to call `scope.$apply()`.

 <pre>
 describe('serviceUnderTest', function() {
@@ -542,95 +552,106 @@ then uses the information it obtains to compose hashbang URLs (such as

 ## Changes to your code

-<table>
-  <tr class="head">
-    <td>Navigation inside the app</td>
-    <td>Change to</td>
-  </tr>
+<table class="table">
+  <thead>
+    <tr class="head">
+      <th>Navigation inside the app</th>
+      <th>Change to</th>
+    </tr>
+  </thead>

-  <tr>
-    <td>$location.href = value<br />$location.hash = value<br />$location.update(value)<br
+  <tbody>
+    <tr>
+      <td>$location.href = value<br />$location.hash = value<br />$location.update(value)<br
 />$location.updateHash(value)</td>
-    <td>$location.path(path).search(search)</td>
-  </tr>
+      <td>$location.path(path).search(search)</td>
+    </tr>

-  <tr>
-    <td>$location.hashPath = path</td>
-    <td>$location.path(path)</td>
-  </tr>
+    <tr>
+      <td>$location.hashPath = path</td>
+      <td>$location.path(path)</td>
+    </tr>

-  <tr>
-    <td>$location.hashSearch = search</td>
-    <td>$location.search(search)</td>
-  </tr>
+    <tr>
+      <td>$location.hashSearch = search</td>
+      <td>$location.search(search)</td>
+    </tr>

-  <tr class="head">
-    <td>Navigation outside the app</td>
-    <td>Use lower level API</td>
-  </tr>
+    <tr class="head">
+      <td>Navigation outside the app</td>
+      <td>Use lower level API</td>
+    </tr>

-  <tr>
-    <td>$location.href = value<br />$location.update(value)</td>
-    <td>$window.location.href = value</td>
-  </tr>
+    <tr>
+      <td>$location.href = value<br />$location.update(value)</td>
+      <td>$window.location.href = value</td>
+    </tr>

-  <tr>
-    <td>$location[protocol | host | port | path | search]</td>
-    <td>$window.location[protocol | host | port | path | search]</td>
-  </tr>
+    <tr>
+      <td>$location[protocol | host | port | path | search]</td>
+      <td>$window.location[protocol | host | port | path | search]</td>
+    </tr>

-  <tr class="head">
-    <td>Read access</td>
-    <td>Change to</td>
-  </tr>
+    <tr class="head">
+      <td>Read access</td>
+      <td>Change to</td>
+    </tr>

-  <tr>
-    <td>$location.hashPath</td>
-    <td>$location.path()</td>
-  </tr>
+    <tr>
+      <td>$location.hashPath</td>
+      <td>$location.path()</td>
+    </tr>

-  <tr>
-    <td>$location.hashSearch</td>
-    <td>$location.search()</td>
-  </tr>
+    <tr>
+      <td>$location.hashSearch</td>
+      <td>$location.search()</td>
+    </tr>

-  <tr>
-    <td>$location.href<br />$location.protocol<br />$location.host<br />$location.port<br
+    <tr>
+      <td>$location.href<br />$location.protocol<br />$location.host<br />$location.port<br
 />$location.hash</td>
-    <td>$location.absUrl()<br />$location.protocol()<br />$location.host()<br />$location.port()<br
+      <td>$location.absUrl()<br />$location.protocol()<br />$location.host()<br />$location.port()<br
 />$location.path() + $location.search()</td>
-  </tr>
+    </tr>

-  <tr>
-    <td>$location.path<br />$location.search</td>
-    <td>$window.location.path<br />$window.location.search</td>
-  </tr>
+    <tr>
+      <td>$location.path<br />$location.search</td>
+      <td>$window.location.path<br />$window.location.search</td>
+    </tr>
+  </tbody>
 </table>

 ## Two-way binding to $location

 The Angular's compiler currently does not support two-way binding for methods (see {@link
-https://github.com/angular/angular.js/issues/404 issue}).  If you should require two-way binding,
-you will need to specify an extra property that has two watchers. For example:
-<pre>
-<!-- html -->
-<input type="text" ng-model="locationPath" />
-</pre>
-<pre>
-// js - controller
-this.$watch('locationPath', function(path) {
-  $location.path(path);
-});
-
-this.$watch('$location.path()', function(path) {
-  scope.locationPath = path;
-});
-</pre>
-
+https://github.com/angular/angular.js/issues/404 issue}).  If you should require two-way binding
+to the $location object (using {@link api/ng.directive:input.text
+ngModel} directive on an input field), you will need to specify an extra model property
+(e.g. `locationPath`) with two watchers which push $location updates in both directions. For
+example:
+<example>
+<file name="index.html">
+<div ng-controller="LocationController">
+  <input type="text" ng-model="locationPath" />
+</div>
+</file>
+<file name="script.js">
+function LocationController($scope, $location) {
+  $scope.$watch('locationPath', function(path) {
+    $location.path(path);
+  });
+  $scope.$watch(function() {
+    return $location.path();
+  }, function(path) {
+    $scope.locationPath = path;
+  });
+}
+</file>
+</example>

 # Related API

-* {@link api/angular.module.ng.$location $location API}
+* {@link api/ng.$location $location API}



@@ -2,12 +2,12 @@
@name Developer Guide: Angular Services: Creating Services
@description

-While angular offers several useful services, for any nontrivial application you'll find it useful
+While Angular offers several useful services, for any nontrivial application you'll find it useful
 to write your own custom services. To do this you begin by registering a service factory function
 with a module either via the {@link api/angular.module Module#factory api} or directly
-via the {@link api/angular.module.AUTO.$provide $provide} api inside of module config function.
+via the {@link api/AUTO.$provide $provide} api inside of module config function.

-All angular services participate in {@link dev_guide.di dependency injection (DI)} by registering
+All Angular services participate in {@link di dependency injection (DI)} by registering
 themselves with Angular's DI system (injector) under a `name` (id) as well as by declaring
 dependencies which need to be provided for the factory function of the registered service. The
 ability to swap dependencies for mocks/stubs/dummies in tests allows for services to be highly
@@ -18,7 +18,7 @@ testable.

 To register a service, you must have a module that this service will be part of. Afterwards, you
 can register the service with the module either via the {@link api/angular.Module Module api} or
-by using the {@link api/angular.module.AUTO.$provide $provide} service in the module configuration
+by using the {@link api/AUTO.$provide $provide} service in the module configuration
 function.The following pseudo-code shows both approaches:

 Using the angular.Module api:
@@ -48,9 +48,9 @@ create this instance when called.

 # Dependencies

-Services can not only be depended upon, but also have its own dependencies. These can be specified
-as arguments of the factory function. {@link dev_guide.di.understanding_di Read more} about the DI
-in Angular and the use of array notation and $inject property to make DI annotation
+Services can not only be depended upon, but can also have their own dependencies. These can be specified
+as arguments of the factory function. {@link di Read more} about dependency injection (DI)
+in Angular and the use of array notation and the $inject property to make DI annotation
 minification-proof.

 Following is an example of a very simple service. This service depends on the `$window` service
@@ -76,17 +76,17 @@ angular.module('myModule', [], function($provide) {

 # Instantiating Angular Services

-All services in Angular are instantiates services lazily, this means that a service will be created
+All services in Angular are instantiated lazily. This means that a service will be created
 only when it is needed for instantiation of a service or an application component that depends on it.
-In other words, angular won't instantiate lazy services unless they are requested directly or
+In other words, Angular won't instantiate services unless they are requested directly or
 indirectly by the application.


 # Services as singletons

-Lastly, it is important to realize that all angular services are application singletons. This means
-that there is only one instance of a given service per injector. Since angular is lethally allergic
-to the global state, it is possible to create multiple injectors, each with its own instance of a
+Lastly, it is important to realize that all Angular services are application singletons. This means
+that there is only one instance of a given service per injector. Since Angular is lethally allergic
+to global state, it is possible to create multiple injectors, each with its own instance of a
 given service, but that is rarely needed, except in tests where this property is crucially
 important.

@@ -101,4 +101,4 @@ important.

 ## Related API

-* {@link api/angular.module.ng Angular Service API}
+* {@link api/ng Angular Service API}
@@ -30,7 +30,7 @@ myController.$inject = ['$location', '$log'];

 <doc:example module="MyServiceModule">
 <doc:source>
-<script type="text/javascript">
+<script>
 angular.
 module('MyServiceModule', []).
 factory('notify', ['$window', function(win) {
@@ -57,6 +57,7 @@ myController.$inject = ['$scope','notify'];
  <p>Let's try this simple notify service, injected into the controller...</p>
  <input ng-init="message='test'" ng-model="message" >
  <button ng-click="callNotify(message);">NOTIFY</button>
+  <p>(you have to click 3 times to see an alert)</p>
 </div>
 </doc:source>
 <doc:scenario>
@@ -74,7 +75,7 @@ Let's rewrite the above example to show the use of this implicit dependency inje

 <doc:example module="MyServiceModuleDI">
 <doc:source>
-<script type="text/javascript">
+<script>
 angular.
 module('MyServiceModuleDI', []).
 factory('notify', function($window) {
@@ -98,6 +99,7 @@ function myController($scope, notify) {
  <p>Let's try the notify service, that is implicitly injected into the controller...</p>
  <input ng-init="message='test'" ng-model="message">
  <button ng-click="callNotify(message);">NOTIFY</button>
+  <p>(you have to click 3 times to see an alert)</p>
 </div>
 </doc:source>
 </doc:example>
@@ -115,4 +117,4 @@ dependencies with the `$inject` property.

 ## Related API

-{@link api/angular.module.ng Angular Service API}
+{@link api/ng Angular Service API}
@@ -39,8 +39,8 @@ function myModuleCfgFn($provide) {
 </pre>


-Here is an example of two services that depend on each other, as well as on other services that are
-provided by Angular's web framework:
+Here is an example of two services, one of which depends on the other and both
+of which depend on other services that are provided by the Angular framework:

 <pre>
 /**
@@ -50,7 +50,7 @@ provided by Angular's web framework:
 * @param {*} message Message to be logged.
 */
  function batchLogModule($provide){
-    $provide.factory('batchLog', ['$defer', '$log', function($defer, $log) {
+    $provide.factory('batchLog', ['$timeout', '$log', function($timeout, $log) {
      var messageQueue = [];

      function log() {
@@ -58,7 +58,7 @@ provided by Angular's web framework:
          $log('batchLog messages: ', messageQueue);
          messageQueue = [];
        }
-        $defer(log, 50000);
+        $timeout(log, 50000);
      }

      // start periodic checking
@@ -76,7 +76,7 @@ provided by Angular's web framework:
    $provide.factory('routeTemplateMonitor',
                ['$route', 'batchLog', '$rootScope',
         function($route,   batchLog,   $rootScope) {
-      $rootScope.$on('$afterRouteChange', function() {
+      $rootScope.$on('$routeChangeSuccess', function() {
        batchLog($route.current ? $route.current.template : null);
      });
    }]);
@@ -88,10 +88,10 @@ provided by Angular's web framework:

 Things to notice in this example:

-* The `batchLog` service depends on the built-in {@link api/angular.module.ng.$defer $defer} and
-{@link api/angular.module.ng.$log $log} services, and allows messages to be logged into the
+* The `batchLog` service depends on the built-in {@link api/ng.$timeout $timeout} and
+{@link api/ng.$log $log} services, and allows messages to be logged into the
 `console.log` in batches.
-* The `routeTemplateMonitor` service depends on the built-in {@link api/angular.module.ng.$route
+* The `routeTemplateMonitor` service depends on the built-in {@link api/ng.$route
 $route} service as well as our custom `batchLog` service.
 * Both of our services use the factory function signature and array notation for inject annotations
 to declare their dependencies. It is important that the order of the string identifiers in the array
@@ -110,5 +110,5 @@ that the injector uses to determine which services and in which order to inject.

 ## Related API

-* {@link api/angular.module.ng Angular Service API}
+* {@link api/ng Angular Service API}
 * {@link api/angular.injector Angular Injector API}
@@ -2,10 +2,9 @@
@name Developer Guide: Angular Services
@description

-Services are a feature that angular brings to client-side web apps from the server side, where
-services have been commonly used for a long time.  Services in angular apps are substitutable
-objects that are wired together using {@link dev_guide.di dependency injection (DI)}. Services are
-most often used with {@link dev_guide.di dependency injection}, also a key feature of angular apps.
+Services are a feature that Angular brings to client-side web apps from the server side, where
+services have been commonly used for a long time. Services in Angular apps are substitutable
+objects that are wired together using {@link di dependency injection (DI)}.


 ## Related Topics
@@ -18,4 +17,4 @@ most often used with {@link dev_guide.di dependency injection}, also a key featu

 ## Related API

-* {@link api/angular.module.ng Angular Service API}
+* {@link api/ng Angular Service API}
@@ -2,7 +2,7 @@
@name Developer Guide: Angular Services: Testing Angular Services
@description

-Following is a unit test for the service in the example in {@link
+The following is a unit test for the 'notify' service in the 'Dependencies' example in {@link
 dev_guide.services.creating_services Creating Angular Services}. The unit test example uses Jasmine
 spy (mock) instead of a real browser alert.

@@ -55,8 +55,8 @@ it('should clear messages after alert', function() {
 * {@link dev_guide.services.understanding_services Understanding Angular Services}
 * {@link dev_guide.services.creating_services Creating Angular Services}
 * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}
-* {@link dev_guide.services.injecting_controllers Injecting Services Into Conrollers}
+* {@link dev_guide.services.injecting_controllers Injecting Services Into Controllers}

 ## Related API

-* {@link api/angular.module.ng Angular Service API}
+* {@link api/ng Angular Service API}
@@ -3,12 +3,12 @@
@description

 Angular services are singletons that carry out specific tasks common to web apps, such as the
-{@link api/angular.module.ng.$http $http service} that provides low level access to the browser's
+{@link api/ng.$http $http service} that provides low level access to the browser's
 `XMLHttpRequest` object.

-To use an angular service, you identify it as a dependency for the dependent (a controller, or
+To use an Angular service, you identify it as a dependency for the dependent (a controller, or
 another service) that depends on the service.  Angular's dependency injection subsystem takes care
-of the rest. The angular injector subsystem is in charge of service instantiation, resolution of
+of the rest. The Angular injector subsystem is in charge of service instantiation, resolution of
 dependencies, and provision of dependencies to factory functions as requested.

 Angular injects dependencies using "constructor" injection (the service is passed in via a factory
@@ -18,19 +18,19 @@ must explicitly define its dependencies by using the `$inject` property.  For ex

        myController.$inject = ['$location'];

-The angular web framework provides a set of services for common operations. Like other core angular
+The Angular web framework provides a set of services for common operations. Like other core Angular
 variables and identifiers, the built-in services always start with `$` (such as `$http` mentioned
 above). You can also create your own custom services.


 ## Related Topics

-* {@link dev_guide.di About Angular Dependency Injection}
+* {@link di About Angular Dependency Injection}
 * {@link dev_guide.services.creating_services Creating Angular Services}
 * {@link dev_guide.services.managing_dependencies Managing Service Dependencies}
 * {@link dev_guide.services.testing_services Testing Angular Services}

 ## Related API

-* {@link api/angular.module.ng Angular Service API}
+* {@link api/ng Angular Service API}
 * {@link api/angular.injector Injector API}
@@ -7,12 +7,20 @@ Angular sets these CSS classes. It is up to your application to provide useful s

 # CSS classes used by angular

+* `ng-scope`
+  - **Usage:** angular applies this class to any element that where a new {@link api/ng.$rootScope.Scope scope}
+    is defined. (see {@link guide/scope scope} guide for more information about scopes)
+
+* `ng-binding`
+  - **Usage:** angular applies this class to any element that is attached to a data binding, via `ng-bind` or
+    {{}} curly braces, for example. (see {@link guide/dev_guide.templates.databinding databinding} guide)
+
 * `ng-invalid`, `ng-valid`
  - **Usage:** angular applies this class to an input widget element if that element's input does
-    notpass validation. (see {@link api/angular.module.ng.$compileProvider.directive.input input} widget).
+    not pass validation. (see {@link api/ng.directive:input input} directive)

 * `ng-pristine`, `ng-dirty`
-  - **Usage:** angular {@link api/angular.module.ng.$compileProvider.directive.input input} widget applies `ng-pristine` class
+  - **Usage:** angular {@link api/ng.directive:input input} directive applies `ng-pristine` class
    to a new input widget element which did not have user interaction. Once the user interacts with
    the input widget the class is changed to `ng-dirty`.

@@ -20,4 +28,4 @@ Angular sets these CSS classes. It is up to your application to provide useful s
 ## Related Topics

 * {@link dev_guide.templates Angular Templates}
-* {@link dev_guide.forms Angular Forms}
+* {@link forms Angular Forms}
@@ -2,8 +2,8 @@
@name Developer Guide: Templates: Data Binding in Angular
@description

-Data-binding in angular web apps is the automatic syncing of data between the model and view
-components.  The way that angular implements data-binding lets you treat the model as the
+Data-binding in Angular web apps is the automatic syncronization of data between the model and view
+components.  The way that Angular implements data-binding lets you treat the model as the
 single-source-of-truth in your application.  The view is a projection of the model at all times.
 When the model changes, the view reflects the change, and vice versa.

@@ -19,12 +19,12 @@ to write code that constantly syncs the view with the model and the model with t
 ## Data Binding in Angular Templates

 <img class="right" src="img/Two_Way_Data_Binding.png"/>
-The way angular templates works is different, as illustrated in the diagram. They are different
+The way Angular templates works is different, as illustrated in the diagram. They are different
 because first the template (which is the uncompiled HTML along with any additional markup or
 directives) is compiled on the browser, and second, the compilation step produces a live view. We
 say live because any changes to the view are immediately reflected in the model, and any changes in
 the model are propagated to the view. This makes the model always the single-source-of-truth for
-the application state, greatly simplifying the programing model for the developer. You can think of
+the application state, greatly simplifying the programming model for the developer. You can think of
 the view as simply an instant projection of your model.

 Because the view is just a projection of the model, the controller is completely separated from the
@@ -34,5 +34,5 @@ isolation without the view and the related DOM/browser dependency.

 ## Related Topics

-* {@link dev_guide.scopes Angular Scopes}
+* {@link scope Angular Scopes}
 * {@link dev_guide.templates Angular Templates}
@@ -2,23 +2,17 @@
@name Developer Guide: Templates: Filters: Creating Angular Filters
@description

-Writing your own filter is very easy: just define a JavaScript function on the `angular.module.ng.$filter`
-object.
-The framework passes in the input value as the first argument to your function. Any filter
-arguments are passed in as additional function arguments.
-
-You can use these variables in the function:
-
-* `this` — The current scope.
-* `this.$element` — The DOM element containing the binding. The `$element` variable allows the
-filter to manipulate the DOM.
+Writing your own filter is very easy: just register a new filter (injectable) factory function with
+your module. This factory function should return a new filter function which takes the input value
+as the first argument. Any filter arguments are passed in as additional arguments to the filter
+function.

 The following sample filter reverses a text string. In addition, it conditionally makes the
-text upper-case and assigns color.
+text upper-case.

 <doc:example module="MyReverseModule">
 <doc:source>
-<script type="text/javascript">
+<script>
  angular.module('MyReverseModule', []).
    filter('reverse', function() {
      return function(input, uppercase) {
@@ -59,8 +53,8 @@ text upper-case and assigns color.
 ## Related Topics

 * {@link dev_guide.templates.filters Understanding Angular Filters}
-* {@link dev_guide.compiler Angular HTML Compiler}
+* {@link compiler Angular HTML Compiler}

 ## Related API

-* {@link api/angular.module.ng.$filter Angular Filter API}
+* {@link api/ng.$filter Angular Filter API}
@@ -2,9 +2,7 @@
@name Developer Guide: Templates: Understanding Angular Filters
@description

-Angular filters format data for display to the user. In addition to formatting data, filters can
-also modify the DOM. This allows filters to handle tasks such as conditionally applying CSS styles
-to filtered output.
+Angular filters format data for display to the user.

 For example, you might have a data object that needs to be formatted according to the locale before
 displaying it to the user. You can pass expressions through a chain of filters like this:
@@ -12,10 +10,7 @@ displaying it to the user. You can pass expressions through a chain of filters l
        name | uppercase

 The expression evaluator simply passes the value of name to
-{@link api/angular.module.ng.$filter.uppercase uppercase filter}.
-
-In addition to formatting data, filters can also modify the DOM. This allows filters to handle
-tasks such as conditionally applying CSS styles to filtered output.
+{@link api/ng.filter:uppercase uppercase filter}.


 ## Related Topics
@@ -25,4 +20,4 @@ tasks such as conditionally applying CSS styles to filtered output.

 ## Related API

-* {@link api/angular.module.ng.$filter Angular Filter API}
+* {@link api/ng.$filter Angular Filter API}
@@ -2,7 +2,7 @@
@name Developer Guide: Templates: Filters: Using Angular Filters
@description

-Filters can be part of any {@link api/angular.module.ng.$rootScope.Scope} evaluation but are typically used to format
+Filters can be part of any {@link api/ng.$rootScope.Scope} evaluation but are typically used to format
 expressions in bindings in your templates:

        {{ expression | filter }}
@@ -19,6 +19,10 @@ You can also pass colon-delimited arguments to filters, for example, to display

        123 | number:2

+Use the same syntax for multiple arguments:
+
+        myArray | orderBy:'timestamp':true
+
 Here are some examples that show values before and after applying different filters to an
 expression in a binding:

@@ -37,4 +41,4 @@ argument that specifies how many digits to display to the right of the decimal p

 ## Related API

-* {@link api/angular.module.ng.$filter Angular Filter API}
+* {@link api/ng.$filter Angular Filter API}
@@ -2,31 +2,31 @@
@name Developer Guide: Understanding Angular Templates
@description

-An angular template is the declarative specification that, along with information from the model
+An Angular template is the declarative specification that, along with information from the model
 and controller, becomes the rendered view that a user sees in the browser. It is the static DOM,
 containing HTML, CSS, and angular-specific elements and angular-specific element attributes.  The
-angular elements and attributes direct angular to add behavior and transform the template DOM into
+Angular elements and attributes direct angular to add behavior and transform the template DOM into
 the dynamic view DOM.

-These are the types of angular elements and element attributes you can use in a template:
+These are the types of Angular elements and element attributes you can use in a template:

-* {@link api/angular.module.ng.$compileProvider.directive Directive} — An attribute or element that
+* {@link guide/directive Directive} — An attribute or element that
  augments an existing DOM element or represents a reusable DOM component - a widget.
-* {@link api/angular.module.ng.$interpolate  Markup} — The double
+* {@link api/ng.$interpolate Markup} — The double
 curly brace notation `{{ }}` to bind expressions to elements is built-in angular markup.
 * {@link dev_guide.templates.filters Filter} — Formats your data for display to the user.
-* {@link dev_guide.forms Form controls} — Lets you validate user input.
+* {@link forms Form controls} — Lets you validate user input.

 Note:  In addition to declaring the elements above in templates, you can also access these elements
 in JavaScript code.

-The following code snippet shows a simple angular template made up of standard HTML tags along with
-angular {@link api/angular.module.ng.$compileProvider.directive directives} and curly-brace bindings
-with {@link dev_guide.expressions expressions}:
+The following code snippet shows a simple Angular template made up of standard HTML tags along with
+Angular {@link guide/directive directives} and curly-brace bindings
+with {@link expression expressions}:

 <pre>
 <html ng-app>
- <!-- Body tag augmented with ng-controller directive  -->
+ <!-- Body tag augmented with ngController directive  -->
 <body ng-controller="MyController">
   <input ng-model="foo" value="bar">
   <!-- Button tag with ng-click directive, and
@@ -41,8 +41,8 @@ with {@link dev_guide.expressions expressions}:
 In a simple single-page app, the template consists of HTML, CSS, and angular directives contained
 in just one HTML file (usually `index.html`). In a more complex app, you can display multiple views
 within one main page using "partials", which are segments of template located in separate HTML
-files.  You "include" the partials in the main page using the {@link api/angular.module.ng.$route
-$route} service in conjunction with the {@link api/angular.module.ng.$compileProvider.directive.ng-view ng-view} directive. An
+files.  You "include" the partials in the main page using the {@link api/ng.$route
+$route} service in conjunction with the {@link api/ng.directive:ngView ngView} directive. An
 example of this technique is shown in the {@link tutorial/ angular tutorial}, in steps seven and
 eight.

@@ -50,7 +50,7 @@ eight.
 ## Related Topics

 * {@link dev_guide.templates.filters Angular Filters}
-* {@link dev_guide.forms Angular Forms}
+* {@link forms Angular Forms}

 ## Related API

@@ -3,37 +3,49 @@
@description

 JavaScript is a dynamically typed language which comes with great power of expression, but it also
-come with almost no-help from the compiler. For this reason we feel very strongly that any code
+comes with almost no help from the compiler. For this reason we feel very strongly that any code
 written in JavaScript needs to come with a strong set of tests. We have built many features into
-angular which makes testing your angular applications easy. So there is no excuse for not do it.
+Angular which makes testing your Angular applications easy. So there is no excuse for not testing.
+
 # It is all about NOT mixing concerns
+
 Unit testing as the name implies is about testing individual units of code. Unit tests try to
-answer the question: Did I think about the logic correctly. Does the sort function order the list
-in the right order. In order to answer such question it is very important that we can isolate it.
-That is because when we are testing the sort function we don't want to be forced into crating
-related pieces such as the DOM elements, or making any XHR calls in getting the data to sort. While
+answer questions such as "Did I think about the logic correctly?" or "Does the sort function order the list
+in the right order?"
+
+In order to answer such question it is very important that we can isolate the unit of code under test.
+That is because when we are testing the sort function we don't want to be forced into creating
+related pieces such as the DOM elements, or making any XHR calls in getting the data to sort.
+
+While
 this may seem obvious it usually is very difficult to be able to call an individual function on a
-typical project. The reason is that the developers often time mix concerns, and they end up with a
+typical project. The reason is that the developers often mix concerns, and they end up with a
 piece of code which does everything. It reads the data from XHR, it sorts it and then it
-manipulates the DOM. With angular we try to make it easy for you to do the right thing, and so we
-provide dependency injection for your XHR (which you can mock out) and we crated abstraction which
+manipulates the DOM.
+
+With Angular we try to make it easy for you to do the right thing, and so we
+provide dependency injection for your XHR (which you can mock out) and we created abstraction which
 allow you to sort your model without having to resort to manipulating the DOM. So that in the end,
 it is easy to write a sort function which sorts some data, so that your test can create a data set,
 apply the function, and assert that the resulting model is in the correct order. The test does not
 have to wait for XHR, or create the right kind of DOM, or assert that your function has mutated the
-DOM in the right way. Angular is written with testability in mind, but it still requires that you
-do the right thing. We tried to make the right thing easy, but angular is not magic, which means if
-you don't follow these, you may very well end up with an untestable application.
+DOM in the right way.

-## Dependency Inject
+## With great power comes great responsibility
+
+Angular is written with testability in mind, but it still requires that you
+do the right thing. We tried to make the right thing easy, but Angular is not magic, which means if
+you don't follow these guidelines you may very well end up with an untestable application.
+
+## Dependency Injection
 There are several ways in which you can get a hold of a dependency:
 1. You could create it using the `new` operator.
-2. You could look for it in a well know place, also known as global singleton.
+2. You could look for it in a well known place, also known as global singleton.
 3. You could ask a registry (also known as service registry) for it. (But how do you get a hold of
-the registry? Must likely by looking it up in a well know place. See #2)
-4. You could expect that the it be handed to you.
+the registry? Most likely by looking it up in a well known place. See #2)
+4. You could expect that it be handed to you.

-Out of the list above only the last of is testable. Lets look at why:
+Out of the four options in the list above, only the last one is testable. Let's look at why:

 ### Using the `new` operator

@@ -52,10 +64,10 @@ function MyClass() {
 }
 </pre>

-The issue becomes, that in tests, we would very much like to instantiate a `MockXHR` which would
+The issue becomes that in tests, we would very much like to instantiate a `MockXHR` which would
 allow us to return fake data and simulate network failures. By calling `new XHR()` we are
-permanently bound to the actual one, and there is no good way to replace it. Yes there is monkey
-patching, that is a bad idea for many reasons, which is outside the scope of this document.
+permanently bound to the actual XHR, and there is no good way to replace it. Yes there is monkey
+patching. That is a bad idea for many reasons which are outside the scope of this document.

 The class above is hard to test since we have to resort to monkey patching:
 <pre>
@@ -69,7 +81,7 @@ XHR = oldXHR; // if you forget this bad things will happen


 ### Global look-up:
-Another way to approach the problem is look for the service in a well known location.
+Another way to approach the problem is to look for the service in a well known location.

 <pre>
 function MyClass() {
@@ -83,17 +95,17 @@ function MyClass() {
 }
 </pre>

-While no new instance of dependency is being created, it is fundamentally the same as `new`, in
+While no new instance of the dependency is being created, it is fundamentally the same as `new`, in
 that there is no good way to intercept the call to `global.xhr` for testing purposes, other then
-through monkey patching. The basic issue for testing is that global variable needs to be mutated in
+through monkey patching. The basic issue for testing is that a global variable needs to be mutated in
 order to replace it with call to a mock method. For further explanation why this is bad see: {@link
 http://misko.hevery.com/code-reviewers-guide/flaw-brittle-global-state-singletons/ Brittle Global
 State & Singletons}

 The class above is hard to test since we have to change global state:
 <pre>
-var oldXHR = glabal.xhr;
-glabal.xhr = function mockXHR() {};
+var oldXHR = global.xhr;
+global.xhr = function mockXHR() {};
 var myClass = new MyClass();
 myClass.doWork();
 // assert that mockXHR got called with the right arguments
@@ -119,19 +131,19 @@ function MyClass() {
 }
 </pre>

-However, where dose the serviceRegistry come from? if it is:
+However, where does the serviceRegistry come from? if it is:
 * `new`-ed up, the the test has no chance to reset the services for testing
 *  global look-up, then the service returned is global as well (but resetting is easier, since
 there is only one global variable to be reset).

 The class above is hard to test since we have to change global state:
 <pre>
-var oldServiceLocator = glabal.serviceLocator;
-glabal.serviceLocator.set('xhr', function mockXHR() {});
+var oldServiceLocator = global.serviceLocator;
+global.serviceLocator.set('xhr', function mockXHR() {});
 var myClass = new MyClass();
 myClass.doWork();
 // assert that mockXHR got called with the right arguments
-glabal.serviceLocator = oldServiceLocator; // if you forget this bad things will happen
+global.serviceLocator = oldServiceLocator; // if you forget this bad things will happen
 </pre>


@@ -164,7 +176,7 @@ myClass.doWork();

 Notice that no global variables were harmed in the writing of this test.

-Angular comes with {@link dev_guide.di dependency-injection} built in which makes the right thing
+Angular comes with {@link di dependency injection} built in which makes the right thing
 easy to do, but you still need to do it if you wish to take advantage of the testability story.

 ## Controllers
@@ -173,7 +185,7 @@ for your application is mixed in with DOM manipulation, it will be hard to test
 below:

 <pre>
-function PasswordController() {
+function PasswordCtrl() {
  // get references to DOM elements
  var msg = $('.ex1 span');
  var input = $('.ex1 input');
@@ -197,7 +209,7 @@ function PasswordController() {
 }
 </pre>

-The code above is problematic from testability, since it requires your test to have the right kind
+The code above is problematic from a testability point of view, since it requires your test to have the right kind
 of DOM present when the code executes. The test would look like this:

 <pre>
@@ -207,7 +219,7 @@ $('body').html('<div class="ex1">')
  .find('div')
    .append(input)
    .append(span);
-var pc = new PasswordController();
+var pc = new PasswordCtrl();
 input.val('abc');
 pc.grade();
 expect(span.text()).toEqual('weak');
@@ -218,36 +230,36 @@ In angular the controllers are strictly separated from the DOM manipulation logi
 a much easier testability story as can be seen in this example:

 <pre>
-function PasswordCntrl() {
-  this.password = '';
-  this.grade = function() {
-    var size = this.password.length;
+function PasswordCtrl($scope) {
+  $scope.password = '';
+  $scope.grade = function() {
+    var size = $scope.password.length;
    if (size > 8) {
-      this.strength = 'strong';
+      $scope.strength = 'strong';
    } else if (size > 3) {
-      this.strength = 'medium';
+      $scope.strength = 'medium';
    } else {
-      this.strength = 'weak';
+      $scope.strength = 'weak';
    }
  };
 }
 </pre>

-and the tests is straight forward
+and the test is straight forward

 <pre>
-var pc = new PasswordController();
-pc.password('abc');
-pc.grade();
-expect(span.strength).toEqual('weak');
+var $scope = {};
+var pc = $controller('PasswordCtrl', { $scope: $scope });
+$scope.password = 'abc';
+$scope.grade();
+expect($scope.strength).toEqual('weak');
 </pre>

 Notice that the test is not only much shorter but it is easier to follow what is going on. We say
 that such a test tells a story, rather then asserting random bits which don't seem to be related.

-
 ## Filters
-{@link api/angular.module.ng.$filter Filters} are functions which transform the data into user readable
+{@link api/ng.$filter Filters} are functions which transform the data into user readable
 format. They are important because they remove the formatting responsibility from the application
 logic, further simplifying the application logic.

@@ -264,18 +276,66 @@ expect(length('abc')).toEqual(3);
 </pre>

 ## Directives
-Directives in angular are responsible for updating the DOM when the state of the model changes.
+Directives in angular are responsible for encapsulating complex functionality within custom HTML tags,
+attributes, classes or comments. Unit tests are very important for directives because the components
+you create with directives may be used throughout your application and in many different contexts.
+
+### Simple HTML Element Directive
+
+Lets start with an angular app with no dependencies.
+
+<pre>
+var app = angular.module('myApp', []);
+</pre>
+
+Now we can add a directive to our app.
+
+<pre>
+app.directive('aGreatEye', function () {
+    return {
+        restrict: 'E',
+        replace:  true,
+        template: '<h1>lidless, wreathed in flame, {{1 + 1}} times</h1>'
+    };
+});
+</pre>
+
+This directive is used as a tag `<a-great-eye></a-great-eye>`. It replaces the entire tag with the
+template `<h1>lidless, wreathed in flame, {{1 + 1}} times</h1>`. Now we are going to write a jasmine unit test to
+verify this functionality. Note that the expression `{{1 + 1}}` times will also be evaluated in the rendered content.
+
+<pre>
+describe('Unit testing great quotes', function() {
+    var $compile;
+    var $rootScope;
+
+    // Load the myApp module, which contains the directive
+    beforeEach(module('myApp'));
+
+    // Store references to $rootScope and $compile
+    // so they are available to all tests in this describe block
+    beforeEach(inject(function(_$compile_, _$rootScope_){
+      // The injector unwraps the underscores (_) from around the parameter names when matching
+      $compile = _$compile_;
+      $rootScope = _$rootScope_;
+    }));
+    
+    it('Replaces the element with the appropriate content', function() {
+        // Compile a piece of HTML containing the directive
+        var element = $compile("<a-great-eye></a-great-eye>")($rootScope);
+        // fire all the watches, so the scope expression {{1 + 1}} will be evaluated
+        $rootScope.$digest();
+        // Check that the compiled element contains the templated content
+        expect(element.html()).toContain("lidless, wreathed in flame, 2 times");
+    });
+});
+</pre>
+
+We inject the $compile service and $rootScope before each jasmine test. The $compile service is used
+to render the aGreatEye directive. After rendering the directive we ensure that the directive has
+replaced the content and "lidless, wreathed in flame, 2 times" is present.


-## Mocks
-oue
-## Global State Isolation
-oue
-# Preferred way of Testing
-uo
-## JavaScriptTestDriver
-ou
-## Jasmine
-ou
 ## Sample project
-uoe
+See the {@link https://github.com/angular/angular-seed angular-seed} project for an example.
+
@@ -0,0 +1,239 @@
+@ngdoc overview
+@name Developer Guide: Dependency Injection
+@description
+
+# Dependency Injection
+
+Dependency Injection (DI) is a software design pattern that deals with how code gets hold of its
+dependencies.
+
+For in-depth discussion about DI, see {@link http://en.wikipedia.org/wiki/Dependency_injection
+Dependency Injection} at Wikipedia, {@link http://martinfowler.com/articles/injection.html
+Inversion of Control} by Martin Fowler, or read about DI in your favorite software design pattern
+book.
+
+## DI in a nutshell
+
+There are only three ways an object or a function can get a hold of its dependencies:
+
+  1. The dependency can be created, typically using the `new` operator.
+
+  2. The dependency can be looked up by referring to a global variable.
+
+  3. The dependency can be passed in to where it is needed.
+
+
+The first two options of creating or looking up dependencies are not optimal because they hard
+code the dependency. This makes it difficult, if not impossible, to modify the dependencies.
+This is especially problematic in tests, where it is often desirable to provide mock dependencies
+for test isolation.
+
+The third option is the most viable, since it removes the responsibility of locating the
+dependency from the component. The dependency is simply handed to the component.
+
+<pre>
+  function SomeClass(greeter) {
+    this.greeter = greeter;
+  }
+  
+  SomeClass.prototype.doSomething = function(name) {
+    this.greeter.greet(name);
+  }
+</pre>
+
+In the above example `SomeClass` is not concerned with locating the `greeter` dependency, it
+is simply handed the `greeter` at runtime.
+
+This is desirable, but it puts the responsibility of getting hold of the dependency on the
+code that constructs `SomeClass`.
+
+To manage the responsibility of dependency creation, each Angular application has an {@link
+api/angular.injector injector}. The injector is a service locator that is responsible for
+construction and lookup of dependencies.
+
+Here is an example of using the injector service:
+
+<pre>
+  // Provide the wiring information in a module
+  angular.module('myModule', []).
+  
+    // Teach the injector how to build a 'greeter'
+    // Notice that greeter itself is dependent on '$window'
+    factory('greeter', function($window) {
+      // This is a factory function, and is responsible for 
+      // creating the 'greet' service.
+      return {
+        greet: function(text) {
+          $window.alert(text);
+        }
+      };
+    });
+
+  // New injector is created from the module. 
+  // (This is usually done automatically by angular bootstrap)
+  var injector = angular.injector(['myModule', 'ng']);
+  
+  // Request any dependency from the injector
+  var greeter = injector.get('greeter');
+</pre>
+
+Asking for dependencies solves the issue of hard coding, but it also means that the injector needs
+to be passed throughout the application. Passing the injector breaks the {@link
+http://en.wikipedia.org/wiki/Law_of_Demeter Law of Demeter}. To remedy this, we turn the
+dependency lookup responsibility to the injector by declaring the dependencies as in this example:
+
+<pre>
+  <!-- Given this HTML -->
+  <div ng-controller="MyController">
+    <button ng-click="sayHello()">Hello</button>
+  </div>
+</pre>  
+<pre>
+  // And this controller definition
+  function MyController($scope, greeter) {
+    $scope.sayHello = function() {
+      greeter.greet('Hello World');
+    };
+  }
+  
+  // The 'ng-controller' directive does this behind the scenes
+  injector.instantiate(MyController);
+</pre>
+
+Notice that by having the `ng-controller` instantiate the class, it can satisfy all of the
+dependencies of `MyController` without the controller ever knowing about the injector. This is
+the best outcome. The application code simply asks for the dependencies it needs, without having to
+deal with the injector. This setup does not break the Law of Demeter.
+
+## Dependency Annotation
+
+How does the injector know what service needs to be injected?
+
+The application developer needs to provide annotation information that the injector uses in order
+to resolve the dependencies. Throughout Angular, certain API functions are invoked using the
+injector, as per the API documentation. The injector needs to know what services to inject into
+the function. Below are three equivalent ways of annotating your code with service name
+information. These can be used interchangeably as you see fit and are equivalent.
+
+### Inferring Dependencies
+
+The simplest way to get hold of the dependencies, is to assume that the function parameter names
+are the names of the dependencies.
+
+<pre>
+  function MyController($scope, greeter) {
+    ...
+  }
+</pre>
+
+Given a function the injector can infer the names of the service to inject by examining the
+function declaration and extracting the parameter names. In the above example `$scope`, and
+`greeter` are two services which need to be injected into the function.
+
+While straightforward, this method will not work with JavaScript minifiers/obfuscators as they
+rename the method parameter names. This makes this way of annotating only useful for {@link
+http://www.pretotyping.org/ pretotyping}, and demo applications.
+
+### `$inject` Annotation
+
+To allow the minifers to rename the function parameters and still be able to inject right services
+the function needs to be annotated with the `$inject` property. The `$inject` property is an array
+of service names to inject.
+
+<pre>
+  var MyController = function(renamed$scope, renamedGreeter) {
+    ...
+  }
+  MyController.$inject = ['$scope', 'greeter'];
+</pre>
+
+In this scenario the ordering of the values in the '$inject' array must match the ordering of the arguments to inject.
+Using above code snippet as an example, '$scope' will be injected into 'renamed$scope' and 'greeter' into 'renamedGreeter'.
+Care must be taken that the `$inject` annotation is kept in sync with the actual arguments in the
+function declaration.
+
+This method of annotation is useful for controller declarations since it assigns the annotation
+information with the function.
+
+### Inline Annotation
+
+Sometimes using the `$inject` annotation style is not convenient such as when annotating
+directives.
+
+For example:
+
+<pre>
+  someModule.factory('greeter', function($window) {
+    ...
+  });
+</pre>
+
+Results in code bloat due to needing a temporary variable:
+
+<pre>
+  var greeterFactory = function(renamed$window) {
+    ...
+  };
+  
+  greeterFactory.$inject = ['$window'];
+  
+  someModule.factory('greeter', greeterFactory);
+</pre>
+
+For this reason the third annotation style is provided as well.
+
+<pre>
+  someModule.factory('greeter', ['$window', function(renamed$window) {
+    ...
+  }]);
+</pre>
+
+Keep in mind that all of the annotation styles are equivalent and can be used anywhere in Angular
+where injection is supported.
+
+## Where can I use DI?
+
+DI is pervasive throughout Angular. It is typically used in controllers and factory methods. 
+
+### DI in controllers
+
+Controllers are classes which are responsible for application behavior. The recommended way of 
+declaring controllers is using the array notation:
+
+<pre>
+  someModule.controller('MyController', ['$scope', 'dep1', 'dep2', function($scope, dep1, dep2) {
+    ...
+    $scope.aMethod = function() {
+      ...
+    }
+    ...
+  }]);
+</pre>
+
+This avoids the creation of global functions for controllers and also protects against minification.
+
+
+### Factory methods
+
+Factory methods are responsible for creating most objects in Angular. Examples are directives,
+services, and filters. The factory methods are registered with the module, and the recommended way
+of declaring factories is:
+
+<pre>
+  angular.module('myModule', []).
+    config(['depProvider', function(depProvider){
+      ...
+    }]).
+    factory('serviceId', ['depService', function(depService) {
+      ...
+    }]).
+    directive('directiveName', ['depService', function(depService) {
+      ...
+    }]).
+    filter('filterName', ['depService', function(depService) {
+      ...
+    }]).
+    run(['depService', function(depService) {
+      ...
+    }]);
+</pre>
@@ -1,5 +1,5 @@
@ngdoc overview
-@name angular.module.ng.$compileProvider.directive
+@name Directives
@description

 Directives are a way to teach HTML new tricks. During DOM compilation directives are matched
@@ -10,7 +10,7 @@ can be extended such that HTML can be turned into a declarative domain specific

 # Invoking directives from HTML

-Directives have camel cased names such as 'ngBind'. The directive can be invoked by translating
+Directives have camel cased names such as `ngBind`. The directive can be invoked by translating
 the camel case name into snake case with these special characters `:`, `-`, or `_`. Optionally the
 directive can be prefixed with `x-`, or `data-` to make it HTML validator compliant. Here is a
 list of some of the possible directive names: `ng:bind`, `ng-bind`, `ng_bind`, `x-ng-bind` and
@@ -27,43 +27,43 @@ attribute only.)
  <!-- directive: my-dir exp -->
 </pre>

-Directives can be invoked in many different ways, but are equivalent in the end result as shown in
-the following example.
+The following demonstrates the various ways a Directive (ngBind in this case) can be referenced from within a template.

 <doc:example>
  <doc:source >
   <script>
     function Ctrl1($scope) {
-       $scope.name = 'angular';
+       $scope.name = 'Max Karl Ernst Ludwig Planck (April 23, 1858 – October 4, 1947)';
     }
   </script>
   <div ng-controller="Ctrl1">
-     Hello <input ng-model='name' ng-model-instant> <hr/>
-     &ltspan ng:bind="name"&gt <span ng:bind="name"></span> <br/>
-     &ltspan ng_bind="name"&gt <span ng_bind="name"></span> <br/>
-     &ltspan ng-bind="name"&gt <span ng-bind="name"></span> <br/>
-     &ltspan data-ng-bind="name"&gt <span data-ng-bind="name"></span> <br/>
-     &ltspan x-ng-bind="name"&gt <span x-ng-bind="name"></span> <br/>
+     Hello <input ng-model='name'> <hr/>
+     &lt;span ng-bind="name"&gt; <span ng-bind="name"></span> <br/>
+     &lt;span ng:bind="name"&gt; <span ng:bind="name"></span> <br/>
+     &lt;span ng_bind="name"&gt; <span ng_bind="name"></span> <br/>
+     &lt;span data-ng-bind="name"&gt; <span data-ng-bind="name"></span> <br/>
+     &lt;span x-ng-bind="name"&gt; <span x-ng-bind="name"></span> <br/>
   </div>
  </doc:source>
  <doc:scenario>
-    it('should load template1.html', function() {
-      expect(element('div[ng-controller="Ctrl1"] span[ng-bind]').text()).toBe('angular');
+    it('should show off bindings', function() {
+      expect(element('div[ng-controller="Ctrl1"] span[ng-bind]').text())
+        .toBe('Max Karl Ernst Ludwig Planck (April 23, 1858 – October 4, 1947)');
    });
  </doc:scenario>
 </doc:example>

 # String interpolation

-During the compilation process the {@link angular.module.ng.$compile compiler} matches text and
-attributes using the {@link angular.module.ng.$interpolate $interpolate} service to see if they
+During the compilation process the {@link api/ng.$compile compiler} matches text and
+attributes using the {@link api/ng.$interpolate $interpolate} service to see if they
 contain embedded expressions. These expressions are registered as {@link
-angular.module.ng.$rootScope.Scope#$watch watches} and will update as part of normal {@link
-angular.module.ng.$rootScope.Scope#$digest digest} cycle. An example of interpolation is shown
+api/ng.$rootScope.Scope#$watch watches} and will update as part of normal {@link
+api/ng.$rootScope.Scope#$digest digest} cycle. An example of interpolation is shown
 here:

 <pre>
-<img src="img/{{username}}.jpg">Hello {{username}}!</img>
+<a href="img/{{username}}.jpg">Hello {{username}}!</a>
 </pre>

 # Compilation process, and directive matching
@@ -72,30 +72,30 @@ Compilation of HTML happens in three phases:

  1. First the HTML is parsed into DOM using the standard browser API. This is important to
  realize because the templates must be parsable HTML. This is in contrast to most templating
-  systems that operate on strings, rather then on DOM elements.
+  systems that operate on strings, rather than on DOM elements.

-  2. The compilation of the DOM is performed by the call to {@link angular.module.ng.$compile
+  2. The compilation of the DOM is performed by the call to the {@link api/ng.$compile
  $compile()} method. The method traverses the DOM and matches the directives. If a match is found
  it is added to the list of directives associated with the given DOM element. Once all directives
  for a given DOM element have been identified they are sorted by priority and their `compile()`
  functions are executed. The directive compile function has a chance to modify the DOM structure
  and is responsible for producing a `link()` function explained next. The {@link
-  angular.module.ng.$compile $compile()} method returns a combined linking function, which is a
+  api/ng.$compile $compile()} method returns a combined linking function, which is a
  collection of all of the linking functions returned from the individual directive compile
  functions.

-  3. Link the template with scope by calling the liking function returned from the previous step.
+  3. Link the template with scope by calling the linking function returned from the previous step.
  This in turn will call the linking function of the individual directives allowing them to
  register any listeners on the elements and set up any {@link
-  angular.module.ng.$rootScope.Scope#$watch watches} with the {@link
-  angular.module.ng.$rootScope.Scope scope}. The result of this is a live binding between the
+  api/ng.$rootScope.Scope#$watch watches} with the {@link
+  api/ng.$rootScope.Scope scope}. The result of this is a live binding between the
  scope and the DOM. A change in the scope is reflected in the DOM.

 <pre>
  var $compile = ...; // injected into your code
  var scope = ...;

-  var html = '<div ng-bind='exp'></div>';
+  var html = '<div ng-bind="exp"></div>';

  // Step 1: parse HTML into DOM element
  var template = angular.element(html);
@@ -109,8 +109,8 @@ Compilation of HTML happens in three phases:

 ## Reasons behind the compile/link separation

-At this point you may wonder why is the compile process broken down to a compile and link phase.
-To understand this, lets look at a real world example with repeater:
+At this point you may wonder why the compile process is broken down to a compile and link phase.
+To understand this, let's look at a real world example with a repeater:

 <pre>
  Hello {{user}}, you have these actions:
@@ -125,49 +125,49 @@ The short answer is that compile and link separation is needed any time a change
 a change in DOM structure such as in repeaters.

 When the above example is compiled, the compiler visits every node and looks for directives. The
-`{{user}}` is an example of {@link angular.module.ng.$interpolate interpolation} directive. {@link
-angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} is another directive. But {@link
-angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} has a dilemma. It needs to be
+`{{user}}` is an example of an {@link api/ng.$interpolate interpolation} directive. {@link
+api/ng.directive:ngRepeat ngRepeat} is another directive. But {@link
+api/ng.directive:ngRepeat ngRepeat} has a dilemma. It needs to be
 able to quickly stamp out new `li`s for every `action` in `user.actions`. This means that it needs
 to save a clean copy of the `li` element for cloning purposes and as new `action`s are inserted,
 the template `li` element needs to be cloned and inserted into `ul`. But cloning the `li` element
 is not enough. It also needs to compile the `li` so that its directives such as
-`{{action.descriptions}}` evaluate against the right {@link angular.module.ng.$rootScope.Scope
-scope}. A naive method would be to simply insert a copy of the `li` elemnt and then compile it.
+`{{action.description}}` evaluate against the right {@link api/ng.$rootScope.Scope
+scope}. A naive method would be to simply insert a copy of the `li` element and then compile it.
 But compiling on every `li` element clone would be slow, since the compilation requires that we
 traverse the DOM tree and look for directives and execute them. If we put the compilation inside a
-repeater which needs to unroll 100 items we would quickly run into performance problem.
+repeater which needs to unroll 100 items we would quickly run into performance problems.

-The solution is to break the compilation process into two phases the compile phase where all of
+The solution is to break the compilation process into two phases; the compile phase where all of
 the directives are identified and sorted by priority, and a linking phase where any work which
-links a specific instance of the {@link angular.module.ng.$rootScope.Scope scope} and the specific
+links a specific instance of the {@link api/ng.$rootScope.Scope scope} and the specific
 instance of an `li` is performed.

-{@link angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} works by preventing the
-compilation process form descending into `li` element. Instead the {@link
-angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} directive compiles `li`
-seperatly. The result of of the `li` element compilation is a linking function which contains all
-of the directives contained in the `li` element ready to be attached to a specific clone of `li`
-element. At runtime the {@link angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat}
+{@link api/ng.directive:ngRepeat ngRepeat} works by preventing the
+compilation process from descending into the `li` element. Instead the {@link
+api/ng.directive:ngRepeat ngRepeat} directive compiles `li`
+separately. The result of the `li` element compilation is a linking function which contains all
+of the directives contained in the `li` element, ready to be attached to a specific clone of the `li`
+element. At runtime the {@link api/ng.directive:ngRepeat ngRepeat}
 watches the expression and as items are added to the array it clones the `li` element, creates a
-new {@link angular.module.ng.$rootScope.Scope scope} for the cloned `li` element and calls the
+new {@link api/ng.$rootScope.Scope scope} for the cloned `li` element and calls the
 link function on the cloned `li`.

 Summary:

  * *compile function* - The compile function is relatively rare in directives, since most
-    directives are concerned with working with a specific DOM element instance rather then
+    directives are concerned with working with a specific DOM element instance rather than
    transforming the template DOM element. Any operation which can be shared among the instance of
    directives should be moved to the compile function for performance reasons.

-  * *link function* - It is rare for the directive not to have a link function. Link function
+  * *link function* - It is rare for the directive not to have a link function. A link function
    allows the directive to register listeners to the specific cloned DOM element instance as well
    as to copy content into the DOM from the scope.


 # Writing directives (short version)

-In this example we will build a directive which displays the current time.
+In this example we will build a directive that displays the current time.

 <doc:example module="time">
  <doc:source>
@@ -178,12 +178,12 @@ In this example we will build a directive which displays the current time.

     angular.module('time', [])
       // Register the 'myCurrentTime' directive factory method.
-       // We inject $defer and dateFilter service since the factory method is DI.
-       .directive('myCurrentTime', function($defer, dateFilter) {
+       // We inject $timeout and dateFilter service since the factory method is DI.
+       .directive('myCurrentTime', function($timeout, dateFilter) {
         // return the directive link function. (compile function not needed)
         return function(scope, element, attrs) {
           var format,  // date format
-               deferId; // deferId, so that we can cancel the time updates
+               timeoutId; // timeoutId, so that we can cancel the time updates

           // used to update the UI
           function updateTime() {
@@ -198,36 +198,39 @@ In this example we will build a directive which displays the current time.

           // schedule update in one second
           function updateLater() {
-             // save the deferId for canceling
-             deferId = $defer(function() {
+             // save the timeoutId for canceling
+             timeoutId = $timeout(function() {
               updateTime(); // update DOM
               updateLater(); // schedule another update
             }, 1000);
           }

           // listen on DOM destroy (removal) event, and cancel the next UI update
-           // to prevent updating time ofter the DOM element was removed.
+           // to prevent updating time after the DOM element was removed.
           element.bind('$destroy', function() {
-             $defer.cancel(deferId);
+             $timeout.cancel(timeoutId);
           });

-           updateLater(); // kick of the UI update process.
+           updateLater(); // kick off the UI update process.
         }
       });
   </script>
   <div ng-controller="Ctrl2">
-     Date format: <input ng-model='format'> <hr/>
-     Current time is: <span my-current-time="format"></span
+     Date format: <input ng-model="format"> <hr/>
+     Current time is: <span my-current-time="format"></span>
   </div>
  </doc:source>
-  <doc:scenario>
-  </doc:scenario>
 </doc:example>


 # Writing directives (long version)

-The full skeleton of the directive is shown here:
+There are different ways to declare a directive. The difference resides in the return
+value of the factory function. You can either return a Directive Definition Object
+(see below) that defines the directive properties, or just the postLink function
+of such an object (all other properties will have the default values).
+
+Here's an example directive declared with a Directive Definition Object:

 <pre>
  var myModule = angular.module(...);
@@ -241,6 +244,8 @@ The full skeleton of the directive is shown here:
      transclude: false,
      restrict: 'A',
      scope: false,
+      controller: ["$scope", "$element", "$attrs", "$transclude", "otherInjectables",
+        function($scope, $element, $attrs, $transclude, otherInjectables) { ... }],
      compile: function compile(tElement, tAttrs, transclude) {
        return {
          pre: function preLink(scope, iElement, iAttrs, controller) { ... },
@@ -253,12 +258,11 @@ The full skeleton of the directive is shown here:
  });
 </pre>

-In most cases you will not need such fine control and so the above can be simplified. All of the
-different parts of this skeleton are explained in following sections. In this section we are
-interested only isomers of this skeleton.
+In most cases you will not need such fine control and so the above can be simplified. You can still
+return a Directive Definition Object, but only setting the 'compile' function property of the Object,
+and rely on the default values for other properties.

-The first step in simplyfing the code is to rely on the deafult values. Therefore the above can be
-simplified as:
+Therefore the above can be simplified as:

 <pre>
  var myModule = angular.module(...);
@@ -273,8 +277,10 @@ simplified as:
  });
 </pre>

-Most directives concern themselves only with instances not with template transformations allowing
-further simplification:
+Finally, most directives concern themselves only with instances, not with template transformations, allowing
+further simplification.
+
+Here we only define the postLink function:

 <pre>
  var myModule = angular.module(...);
@@ -288,22 +294,23 @@ further simplification:
 ## Factory method

 The factory method is responsible for creating the directive. It is invoked only once, when the
-{@link angular.module.ng.$compile compiler} matches the directive for the first time. You can
+{@link api/ng.$compile compiler} matches the directive for the first time. You can
 perform any initialization work here. The method is invoked using the {@link
-http://localhost:8000/build/docs/api/angular.module.AUTO.$injector#invoke $injector.invoke} which
+api/AUTO.$injector#invoke $injector.invoke} which
 makes it injectable following all of the rules of injection annotation.

 ## Directive Definition Object

-The directive definition object provides instructions to the {@link angular.module.ng.$compile
+The directive definition object provides instructions to the {@link api/ng.$compile
 compiler}. The attributes are:

-  * `name` - Name of the current scope. Optional defaults to the name at registration.
+  * `name` - Name of the current scope. Optional and defaults to the name at registration.

  * `priority` - When there are multiple directives defined on a single DOM element, sometimes it
    is necessary to specify the order in which the directives are applied. The `priority` is used
-    to sort the directives before their `compile` functions get called. Higher `priority` goes
-    first. The order of directives within the same priority is undefined.
+    to sort the directives before their `compile` functions get called. Priority is defined as a
+    number. Directives with greater numerical `priority` are compiled first. The order of directives with
+    the same priority is undefined. The default priority is `0`.

  * `terminal` - If set to true then the current `priority` will be the last set of directives
    which will execute (any directives at the current priority will still execute
@@ -312,55 +319,61 @@ compiler}. The attributes are:
  * `scope` - If set to:

    * `true` - then a new scope will be created for this directive. If multiple directives on the
-      same element request new scope, only one new scope is created. The new scope rule does not
+      same element request a new scope, only one new scope is created. The new scope rule does not
      apply for the root of the template since the root of the template always gets a new scope.

    * `{}` (object hash) - then a new 'isolate' scope is created. The 'isolate' scope differs from
-      normal scope that it does not prototypically inherit from the parent scope. This is useful
-      when creating reusable components, which should not accidentally read or modify data in
+      normal scope in that it does not prototypically inherit from the parent scope. This is useful
+      when creating reusable components, which should not accidentally read or modify data in the
      parent scope. <br/>
      The 'isolate' scope takes an object hash which defines a set of local scope properties
      derived from the parent scope. These local properties are useful for aliasing values for
-      templates. Locals definition is a hash of normalized element attribute name to their
-      corresponding binding strategy. Valid binding strategies are:
+      templates. Locals definition is a hash of local scope property to its source:

-      * `attribute` - one time read of element attribute value and save it to widget scope. <br/>
-        Given `<widget my-attr='abc'>` and widget definition of `scope: {myAttr:'attribute'}`,
-        then widget scope property `myAttr` will be `"abc"`.
+      * `@` or `@attr` - bind a local scope property to the value of DOM attribute. The result is
+        always a string since DOM attributes are strings. If no `attr` name is specified  then the
+        attribute name is assumed to be the same as the local name.
+        Given `<widget my-attr="hello {{name}}">` and widget definition
+        of `scope: { localName:'@myAttr' }`, then widget scope property `localName` will reflect
+        the interpolated value of `hello {{name}}`. As the `name` attribute changes so will the
+        `localName` property on the widget scope. The `name` is read from the parent scope (not
+        component scope).

-      * `evaluate` - one time evaluation of expression stored in the attribute. <br/> Given
-        `<widget my-attr='name'>` and widget definition of `scope: {myAttr:'evaluate'}`, and
-        parent scope `{name:'angular'}` then widget scope property `myAttr` will be `"angular"`.
+      * `=` or `=attr` - set up bi-directional binding between a local scope property and the
+        parent scope property of name defined via the value of the `attr` attribute. If no `attr`
+        name is specified then the attribute name is assumed to be the same as the local name.
+        Given `<widget my-attr="parentModel">` and widget definition of
+        `scope: { localModel:'=myAttr' }`, then widget scope property `localModel` will reflect the
+        value of `parentModel` on the parent scope. Any changes to `parentModel` will be reflected
+        in `localModel` and any changes in `localModel` will reflect in `parentModel`.

-      * `bind` - Set up one way binding from the element attribute to the widget scope. <br/>
-        Given `<widget my-attr='{{name}}'>` and widget definition of `scope: {myAttr:'bind'}`,
-        and parent scope `{name:'angular'}` then widget scope property `myAttr` will be
-        `"angular"`, but any changes in the parent scope will be reflected in the widget scope.
-
-      * `accessor` - Set up getter/setter function for the expression in the widget element
-        attribute to the widget scope. <br/> Given `<widget my-attr='name'>` and widget definition
-        of `scope: {myAttr:'prop'}`, and parent scope `{name:'angular'}` then widget scope
-        property `myAttr` will be a function such that `myAttr()` will return `"angular"` and
-        `myAttr('new value')` will update the parent scope `name` property. This is useful for
-        treating the element as a data-model for reading/writing.
-
-      * `expression` - Treat element attribute as an expression to be executed on the parent scope.
-        <br/>
-        Given `<widget my-attr='doSomething()'>` and widget definition of `scope:
-        {myAttr:'expression'}`, and parent scope `{doSomething:function() {}}` then calling the
-        widget scope function `myAttr` will execute the expression against the parent scope.
+      * `&` or `&attr` - provides a way to execute an expression in the context of the parent scope.
+        If no `attr` name is specified then the attribute name is assumed to be the same as the
+        local name. Given `<widget my-attr="count = count + value">` and widget definition of
+        `scope: { localFn:'&myAttr' }`, then isolate scope property `localFn` will point to
+        a function wrapper for the `count = count + value` expression. Often it's desirable to
+        pass data from the isolated scope via an expression and to the parent scope, this can be
+        done by passing a map of local variable names and values into the expression wrapper fn.
+        For example, if the expression is `increment(amount)` then we can specify the amount value
+        by calling the `localFn` as `localFn({amount: 22})`.

  * `controller` - Controller constructor function. The controller is instantiated before the
    pre-linking phase and it is shared with other directives if they request it by name (see
    `require` attribute). This allows the directives to communicate with each other and augment
-    each other behavior. The controller is injectable with the following locals:
+    each other's behavior. The controller is injectable with the following locals:

    * `$scope` - Current scope associated with the element
    * `$element` - Current element
-    * `$attrs` - Current attributes obeject for the element
+    * `$attrs` - Current attributes object for the element
    * `$transclude` - A transclude linking function pre-bound to the correct transclusion scope:
      `function(cloneLinkingFn)`.

+    To avoid errors after minification the bracket notation should be used:
+
+    <pre>
+    controller: ['$scope', '$element', '$attrs', '$transclude', function($scope, $element, $attrs, $transclude) { ... }]
+    </pre>
+
  * `require` - Require another controller be passed into current directive linking function. The
    `require` takes a name of the directive controller to pass in. If no such controller can be
    found an error is raised. The name can be prefixed with:
@@ -369,32 +382,6 @@ compiler}. The attributes are:
    * `^` - Look for the controller on parent elements as well.


-  * `inject` (object hash) -  Specifies a way to inject bindings into a controller. Injection
-    definition is a hash of normalized element attribute names to their corresponding binding
-    strategy. Valid binding strategies are:
-
-    * `attribute` - inject attribute value. <br/>
-      Given `<widget my-attr='abc'>` and widget definition of `inject: {myAttr:'attribute'}`, then
-      `myAttr` will inject `"abc"`.
-
-    * `evaluate` - inject one time evaluation of expression stored in the attribute. <br/>
-      Given `<widget my-attr='name'>` and widget definition of `inject: {myAttr:'evaluate'}`, and
-      parent scope `{name:'angular'}` then `myAttr` will inject `"angular"`.
-
-    * `accessor` - inject a getter/setter function for the expression in the widget element
-      attribute to the widget scope. <br/>
-      Given `<widget my-attr='name'>` and widget definition of `inject: {myAttr:'prop'}`, and
-      parent scope `{name:'angular'}` then injecting `myAttr` will inject a function such
-      that `myAttr()` will return `"angular"` and `myAttr('new value')` will update the parent
-      scope `name` property. This is usefull for treating the element as a data-model for
-      reading/writing.
-
-    * `expression` - Inject expression function. <br/>
-      Given `<widget my-attr='doSomething()'>` and widget definition of
-      `inject: {myAttr:'expression'}`, and parent scope `{doSomething:function() {}}` then
-      injecting `myAttr` will inject a function which when called will execute the expression
-      against the parent scope.
-
  * `restrict` - String of subset of `EACM` which restricts the directive to a specific directive
    declaration style. If omitted directives are allowed on attributes only.

@@ -404,19 +391,19 @@ compiler}. The attributes are:
    * `M` - Comment: `<!-- directive: my-directive exp -->`

  * `template` - replace the current element with the contents of the HTML. The replacement process
-    migrates all of the attributes / classes from the old element to the new one. See Creating
-    Widgets section below for more information.
+    migrates all of the attributes / classes from the old element to the new one. See the
+    {@link guide/directive#Components Creating Components} section below for more information.

-  * `templateURL` - Same as `template` but the template is loaded from the specified URL. Because
+  * `templateUrl` - Same as `template` but the template is loaded from the specified URL. Because
    the template loading is asynchronous the compilation/linking is suspended until the template
    is loaded.

-  * `replace` - if set to `true` then the template will replace the current element, rather then
+  * `replace` - if set to `true` then the template will replace the current element, rather than
    append the template to the element.

  * `transclude` - compile the content of the element and make it available to the directive.
-    Typically used with {@link api/angular.module.ng.$compileProvider.directive.ng-transclude
-    ng-transclude}. The advantage of transclusion is that the linking function receives a
+    Typically used with {@link api/ng.directive:ngTransclude
+    ngTransclude}. The advantage of transclusion is that the linking function receives a
    transclusion function which is pre-bound to the correct scope. In a typical setup the widget
    creates an `isolate` scope, but the transclusion is not a child, but a sibling of the `isolate`
    scope. This makes it possible for the widget to have private state, and the transclusion to
@@ -437,31 +424,31 @@ compiler}. The attributes are:
  function compile(tElement, tAttrs, transclude) { ... }
 </pre>

-Compile function deals with transforming the template DOM. Since most directives do not do
-template transformation, it is not used often. Examples which require compile functions are
-directives which transform template DOM such as {@link
-angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} or load the contents
-asynchronously such as {@link angular.module.ng.$compileProvider.directive.ng-view ng-view}. The
-compile functions takes the following arguments.
+The compile function deals with transforming the template DOM. Since most directives do not do
+template transformation, it is not used often. Examples that require compile functions are
+directives that transform template DOM, such as {@link
+api/ng.directive:ngRepeat ngRepeat}, or load the contents
+asynchronously, such as {@link api/ng.directive:ngView ngView}. The
+compile function takes the following arguments.

  * `tElement` - template element - The element where the directive has been declared. It is
    safe to do template transformation on the element and child elements only.

  * `tAttrs` - template attributes - Normalized list of attributes declared on this element shared
    between all directive compile functions. See {@link
-    #Attributes Attributes}
+    guide/directive#Attributes Attributes}.

  * `transclude` - A transclude linking function: `function(scope, cloneLinkingFn)`.

 NOTE: The template instance and the link instance may not be the same objects if the template has
-been cloned. For this reason it is not safe in the compile function to do anything other the DOM
+been cloned. For this reason it is not safe in the compile function to do anything other than DOM
 transformation that applies to all DOM clones. Specifically, DOM listener registration should be
 done in a linking function rather than in a compile function.

 A compile function can have a return value which can be either a function or an object.

-* returning a function - is equivalent to registering the linking function via the `link` property
-  of the config object when the compile function is empty.
+* returning a (post-link) function - is equivalent to registering the linking function via the
+  `link` property of the config object when the compile function is empty.

 * returning an object with function(s) registered via `pre` and `post` properties - allows you to
  control when a linking function should be called during the linking phase. See info about
@@ -474,19 +461,20 @@ A compile function can have a return value which can be either a function or an
  function link(scope, iElement, iAttrs, controller) { ... }
 </pre>

-Link function is responsible for registering DOM listeners as well as updating the DOM. It is
+The link function is responsible for registering DOM listeners as well as updating the DOM. It is
 executed after the template has been cloned. This is where most of the directive logic will be
 put.

-  * `scope` - {@link angular.module.ng.$rootScope.Scope Scope} - The scope to be used by the
-    directive for registering {@link angular.module.ng.$rootScope.Scope#$watch watches}.
+  * `scope` - {@link api/ng.$rootScope.Scope Scope} - The scope to be used by the
+    directive for registering {@link api/ng.$rootScope.Scope#$watch watches}.

  * `iElement` - instance element - The element where the directive is to be used. It is safe to
    manipulate the children of the element only in `postLink` function since the children have
    already been linked.

  * `iAttrs` - instance attributes - Normalized list of attributes declared on this element shared
-    between all directive linking functions. See {@link #Attributes Attributes}
+    between all directive linking functions. See {@link
+    guide/directive#Attributes Attributes}.

  * `controller` - a controller instance - A controller instance if at least one directive on the
    element defines a controller. The controller is shared among all the directives, which allows
@@ -501,16 +489,16 @@ compiler linking function will fail to locate the correct elements for linking.

 ### Post-linking function

-Executed after the child elements are linked. Safe to do DOM transformation in here.
+Executed after the child elements are linked. It is safe to do DOM transformation in the post-linking function.

 <a name="Attributes"></a>
 ## Attributes

-The attributes object - passed as a parameter in the link() or compile() functions - is a way of
-accessing:
+The {@link api/ng.$compile.directive.Attributes Attributes} object - passed as a parameter in the
+link() or compile() functions - is a way of accessing:

  * *normalized attribute names:* Since a directive such as 'ngBind' can be expressed in many ways
-    sucha s as 'ng:bind', or 'x-ng-bind', the attributes object allows for a normalize accessed to
+    such as 'ng:bind', or 'x-ng-bind', the attributes object allows for normalized access to
    the attributes.

  * *directive inter-communication:* All directives share the same instance of the attributes
@@ -555,6 +543,7 @@ dialog component may work.
            on-ok="show = false; doSomething()">
       Body goes here: {{username}} is {{title}}.
    </dialog>
+  </div>
 </pre>

 Clicking on the "show" button will open the dialog. The dialog will have a title, which is
@@ -564,7 +553,7 @@ into the dialog.
 Here is an example of what the template definition for the `dialog` widget may look like.

 <pre>
-  <div ng-show="show()">
+  <div ng-show="visible">
    <h3>{{title}}</h3>
    <div class="body" ng-transclude></div>
    <div class="footer">
@@ -576,18 +565,18 @@ Here is an example of what the template definition for the `dialog` widget may l

 This will not render properly, unless we do some scope magic.

-The first issue we have to solve is that the dialog box template expect `title` to be defined, but
-the place of instantiation would like to bind to `username`. Furthermore the buttons expect `onOk`
-as well as `onCancel` functions to be present in the scope. This limits the usefulness of the
+The first issue we have to solve is that the dialog box template expects `title` to be defined, but
+the place of instantiation would like to bind to `username`. Furthermore the buttons expect the
+`onOk` and `onCancel` functions to be present in the scope. This limits the usefulness of the
 widget. To solve the mapping issue we use the `locals` to create local variables which the template
 expects as follows:

 <pre>
  scope: {
-    title: 'bind',   // set up title to accept data-binding
-    onOk: 'exp',     // create a delegate onOk function
-    onCancel: 'exp', // create a delegate onCancel function
-    show: 'prop'     // create a getter/setter function for visibility.
+    title: '@',             // the title uses the data-binding from the parent scope
+    onOk: '&',              // create a delegate onOk function
+    onCancel: '&',          // create a delegate onCancel function
+    visible: '='            // set up visible to accept data-binding
  }
 </pre>

@@ -605,12 +594,12 @@ To solve the issue of lack of isolation, the directive declares a new `isolated`
 isolated scope does not prototypically inherit from the child scope, and therefore we don't have
 to worry about accidentally clobbering any properties.

-However 'isolated' scope creates a new problem: if a transcluded DOM is a child of the widget
+However `isolated` scope creates a new problem: if a transcluded DOM is a child of the widget
 isolated scope then it will not be able to bind to anything. For this reason the transcluded scope
 is a child of the original scope, before the widget created an isolated scope for its local
 variables. This makes the transcluded and widget isolated scope siblings.

-This may seem as unexpected complexity, but it gives the widget user and developer the least
+This may seem to be unexpected complexity, but it gives the widget user and developer the least
 surprise.

 Therefore the final directive definition looks something like this:
@@ -618,13 +607,16 @@ Therefore the final directive definition looks something like this:
 <pre>
 transclude: true,
 scope: {
-  title: 'bind',   // set up title to accept data-binding
-  onOk: 'exp',     // create a delegate onOk function
-  onCancel: 'exp', // create a delegate onCancel function
-  show: 'prop'     // create a getter/setter function for visibility.
-}
+    title: '@',             // the title uses the data-binding from the parent scope
+    onOk: '&',              // create a delegate onOk function
+    onCancel: '&',          // create a delegate onCancel function
+    visible: '='            // set up visible to accept data-binding
+},
+restrict: 'E',
+replace: true
 </pre>

+<a name="Components"></a>
 # Creating Components

 It is often desirable to replace a single directive with a more complex DOM structure. This
@@ -633,7 +625,6 @@ can be built.

 Following is an example of building a reusable widget.

-
 <doc:example module="zippyModule">
  <doc:source>
   <script>
@@ -649,17 +640,17 @@ Following is an example of building a reusable widget.
           // This HTML will replace the zippy directive.
           replace: true,
           transclude: true,
-           scope: { zippyTitle:'bind' },
+           scope: { title:'@zippyTitle' },
           template: '<div>' +
-                       '<div class="title">{{zippyTitle}}</div>' +
+                       '<div class="title">{{title}}</div>' +
                       '<div class="body" ng-transclude></div>' +
                     '</div>',
           // The linking function will add behavior to the template
           link: function(scope, element, attrs) {
-                 // Title element
+             // Title element
             var title = angular.element(element.children()[0]),
-                 // Opened / closed state
-                 opened = true;
+             // Opened / closed state
+             opened = true;

             // Clicking on title should open/close the zippy
             title.bind('click', toggle);
@@ -0,0 +1,186 @@
+@ngdoc overview
+@name Developer Guide: Expressions
+@description
+
+Expressions are JavaScript-like code snippets that are usually placed in bindings such as `{{
+expression }}`. Expressions are processed by the {@link api/ng.$parse $parse}
+service.
+
+For example, these are all valid expressions in angular:
+
+  * `1+2`
+  * `3*10 | currency`
+  * `user.name`
+
+
+## Angular Expressions vs. JS Expressions
+
+It might be tempting to think of Angular view expressions as JavaScript expressions, but that is
+not entirely correct, since Angular does not use a JavaScript `eval()` to evaluate expressions.
+You can think of Angular expressions as JavaScript expressions with following differences:
+
+  * **Attribute Evaluation:** evaluation of all properties are against the scope, doing the
+    evaluation, unlike in JavaScript where the expressions are evaluated against the global
+    `window`.
+
+  * **Forgiving:** expression evaluation is forgiving to `undefined` and `null`, unlike in JavaScript,
+    where trying to evaluate undefined properties can generate `ReferenceError` or `TypeError`.
+
+  * **No Control Flow Statements:** you cannot do any of the following in angular expression:
+    conditionals, loops, or throw.
+
+  * **Filters:** you can pass result of expression evaluations through filter chains. For example
+    to convert date object into a local specific human-readable format.
+
+If, on the other hand, you do want to run arbitrary JavaScript code, you should make it a
+controller method and call the method. If you want to `eval()` an angular expression from
+JavaScript, use the {@link api/ng.$rootScope.Scope#$eval `$eval()`} method.
+
+## Example
+<doc:example>
+<doc:source>
+ 1+2={{1+2}}
+</doc:source>
+<doc:scenario>
+ it('should calculate expression in binding', function() {
+   expect(binding('1+2')).toEqual('3');
+ });
+</doc:scenario>
+</doc:example>
+
+You can try evaluating different expressions here:
+
+<doc:example>
+<doc:source>
+ <script>
+   function Cntl2($scope) {
+     var exprs = $scope.exprs = [];
+     $scope.expr = '3*10|currency';
+     $scope.addExp = function(expr) {
+        exprs.push(expr);
+     };
+
+     $scope.removeExp = function(index) {
+       exprs.splice(index, 1);
+     };
+   }
+ </script>
+ <div ng-controller="Cntl2" class="expressions">
+   Expression:
+   <input type='text' ng-model="expr" size="80"/>
+   <button ng-click="addExp(expr)">Evaluate</button>
+   <ul>
+    <li ng-repeat="expr in exprs">
+      [ <a href="" ng-click="removeExp($index)">X</a> ]
+      <tt>{{expr}}</tt> => <span ng-bind="$parent.$eval(expr)"></span>
+     </li>
+   </ul>
+ </div>
+</doc:source>
+<doc:scenario>
+ it('should allow user expression testing', function() {
+    element('.expressions :button').click();
+    var li = using('.expressions ul').repeater('li');
+    expect(li.count()).toBe(1);
+    expect(li.row(0)).toEqual(["3*10|currency", "$30.00"]);
+ });
+</doc:scenario>
+</doc:example>
+
+
+# Property Evaluation
+
+Evaluation of all properties takes place against a scope. Unlike JavaScript, where names default
+to global window properties, Angular expressions have to use {@link api/ng.$window
+`$window`} to refer to the global `window` object. For example, if you want to call `alert()`, which is
+defined on `window`, in an expression you must use `$window.alert()`. This is done intentionally to
+prevent accidental access to the global state (a common source of subtle bugs).
+
+<doc:example>
+<doc:source>
+ <script>
+   function Cntl1($window, $scope){
+     $scope.name = 'World';
+
+     $scope.greet = function() {
+       ($window.mockWindow || $window).alert('Hello ' + $scope.name);
+     }
+   }
+ </script>
+ <div class="example2" ng-controller="Cntl1">
+   Name: <input ng-model="name" type="text"/>
+   <button ng-click="greet()">Greet</button>
+ </div>
+</doc:source>
+<doc:scenario>
+ it('should calculate expression in binding', function() {
+   var alertText;
+   this.addFutureAction('set mock', function($window, $document, done) {
+     $window.mockWindow = {
+       alert: function(text){ alertText = text; }
+     };
+     done();
+   });
+   element(':button:contains(Greet)').click();
+   expect(this.addFuture('alert text', function(done) {
+     done(null, alertText);
+   })).toBe('Hello World');
+ });
+</doc:scenario>
+</doc:example>
+
+## Forgiving
+
+Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating `a.b.c` throws
+an exception if `a` is not an object. While this makes sense for a general purpose language, the
+expression evaluations are primarily used for data binding, which often look like this:
+
+        {{a.b.c}}
+
+It makes more sense to show nothing than to throw an exception if `a` is undefined (perhaps we are
+waiting for the server response, and it will become defined soon). If expression evaluation wasn't
+forgiving we'd have to write bindings that clutter the code, for example: `{{((a||{}).b||{}).c}}`
+
+Similarly, invoking a function `a.b.c()` on undefined or null simply returns undefined.
+
+
+## No Control Flow Statements
+
+You cannot write a control flow statement in an expression. The reason behind this is core to the
+Angular philosophy that application logic should be in controllers, not in the view. If you need a
+conditional, loop, or to throw from a view expression, delegate to a JavaScript method instead.
+
+
+## Filters
+
+When presenting data to the user, you might need to convert the data from its raw format to a
+user-friendly format. For example, you might have a data object that needs to be formatted
+according to the locale before displaying it to the user. You can pass expressions through a chain
+of filters like this:
+
+       name | uppercase
+
+The expression evaluator simply passes the value of name to {@link
+api/ng.filter:uppercase `uppercase`} filter.
+
+Chain filters using this syntax:
+
+       value | filter1 | filter2
+
+You can also pass colon-delimited arguments to filters, for example, to display the number 123
+with 2 decimal points:
+
+       123 | number:2
+
+# The $
+
+You might be wondering, what is the significance of the $ prefix? It is simply a prefix that
+angular uses, to differentiate its API names from others. If angular didn't use $, then evaluating
+`a.length()` would return undefined because neither a nor angular define such a property.
+
+Consider that in a future version of Angular we might choose to add a length method, in which case
+the behavior of the expression would change. Worse yet, you, the developer, could create a length
+property and then we would have a collision. This problem exists because Angular augments existing
+objects with additional behavior. By prefixing its additions with $ we are reserving our namespace
+so that angular developers and developers who use Angular can develop in harmony without collisions.
+
@@ -1,9 +1,9 @@
@ngdoc overview
-@name Developer Guide: Forms
+@name Forms
@description

-Controls (`input`, `select`, `textarea`) are a way for user to enter data.
-Form is a collection of controls for the purpose of grouping related controls together.
+Controls (`input`, `select`, `textarea`) are ways for a user to enter data.
+A Form is a collection of controls for the purpose of grouping related controls together.

 Form and controls provide validation services, so that the user can be notified of invalid input.
 This provides a better user experience, because the user gets instant feedback on how to correct the error.
@@ -12,15 +12,15 @@ Server-side validation is still necessary for a secure application.


 # Simple form
-The key directive in understanding two-way data-binding is  {@link api/angular.module.ng.$compileProvider.directive.ng-model ng-model}.
-The `ng-model` provides the two-way data-binding by synchronizing the model to the view, as well as view to the model.
-In addition it provides {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController API} for other directives to augment its behavior.
+The key directive in understanding two-way data-binding is {@link api/ng.directive:ngModel ngModel}.
+The `ngModel` directive provides the two-way data-binding by synchronizing the model to the view, as well as view to the model.
+In addition it provides an {@link api/ng.directive:ngModel.NgModelController API} for other directives to augment its behavior.

 <doc:example>
 <doc:source>
 <div ng-controller="Controller">
  <form novalidate class="simple-form">
-    Name: <input type="text" ng-model="user.name" ng-model-instant /><br />
+    Name: <input type="text" ng-model="user.name" /><br />
    E-mail: <input type="email" ng-model="user.email" /><br />
    Gender: <input type="radio" ng-model="user.gender" value="male" />male
    <input type="radio" ng-model="user.gender" value="female" />female<br />
@@ -31,7 +31,7 @@ In addition it provides {@link api/angular.module.ng.$compileProvider.directive.
  <pre>master = {{master | json}}</pre>
 </div>

-<script type="text/javascript">
+<script>
  function Controller($scope) {
    $scope.master= {};

@@ -50,24 +50,20 @@ In addition it provides {@link api/angular.module.ng.$compileProvider.directive.
 </doc:example>


-Note that:
-
-  * the {@link api/angular.module.ng.$compileProvider.directive.ng-model-instant ng-model-instant} causes the `user.name` to be updated immediately.
-
-  * `novalidate` is used to disable browser's native form validation.
+Note that `novalidate` is used to disable browser's native form validation.



 # Using CSS classes

-To allow styling of form as well as controls, `ng-model`  add these CSS classes:
+To allow styling of form as well as controls, `ngModel`  add these CSS classes:

 - `ng-valid`
 - `ng-invalid`
 - `ng-pristine`
 - `ng-dirty`

-Following example uses the CSS to display validity of each form control.
+The following example uses the CSS to display validity of each form control.
 In the example both `user.name` and `user.email` are required, but are rendered with red background only when they are dirty.
 This ensures that the user is not distracted with an error until after interacting with the control, and failing to satisfy its validity.

@@ -76,7 +72,7 @@ This ensures that the user is not distracted with an error until after interacti
 <div ng-controller="Controller">
  <form novalidate class="css-form">
    Name:
-      <input type="text" ng-model="user.name" ng-model-instant required /><br />
+      <input type="text" ng-model="user.name" required /><br />
    E-mail: <input type="email" ng-model="user.email" required /><br />
    Gender: <input type="radio" ng-model="user.gender" value="male" />male
    <input type="radio" ng-model="user.gender" value="female" />female<br />
@@ -95,12 +91,12 @@ This ensures that the user is not distracted with an error until after interacti
  }
 </style>

-<script type="text/javascript">
+<script>
  function Controller($scope) {
-    $scope.master= {};
+    $scope.master = {};

    $scope.update = function(user) {
-      $scope.master= angular.copy(user);
+      $scope.master = angular.copy(user);
    };

    $scope.reset = function() {
@@ -117,9 +113,9 @@ This ensures that the user is not distracted with an error until after interacti

 # Binding to form and control state

-A form is in instance of {@link api/angular.module.ng.$compileProvider.directive.form.FormController FormController}.
+A form is an instance of {@link api/ng.directive:form.FormController FormController}.
 The form instance can optionally be published into the scope using the `name` attribute.
-Similarly control is an instance of {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController NgModelController}.
+Similarly control is an instance of {@link api/ng.directive:ngModel.NgModelController NgModelController}.
 The control instance can similarly be published into the form instance using the `name` attribute.
 This implies that the internal state of both the form and the control is available for binding in the view using the standard binding primitives.

@@ -147,21 +143,21 @@ This allows us to extend the above example with these features:

    <input type="checkbox" ng-model="user.agree" name="userAgree" required />
    I agree: <input ng-show="user.agree" type="text" ng-model="user.agreeSign"
-              ng-model-instant required /><br />
+              required /><br />
    <div ng-show="!user.agree || !user.agreeSign">Please agree and sign.</div>

-    <button ng-click="reset()" disabled="{{isUnchanged(user)}}">RESET</button>
+    <button ng-click="reset()" ng-disabled="isUnchanged(user)">RESET</button>
    <button ng-click="update(user)"
-            disabled="{{form.$invalid || isUnchanged(user)}}">SAVE</button>
+            ng-disabled="form.$invalid || isUnchanged(user)">SAVE</button>
  </form>
 </div>

-<script type="text/javascript">
+<script>
  function Controller($scope) {
-    $scope.master= {};
+    $scope.master = {};

    $scope.update = function(user) {
-      $scope.master= angular.copy(user);
+      $scope.master = angular.copy(user);
    };

    $scope.reset = function() {
@@ -182,30 +178,30 @@ This allows us to extend the above example with these features:

 # Custom Validation

-Angular provides basic implementation for most common html5 {@link api/angular.module.ng.$compileProvider.directive.input input}
-types: ({@link api/angular.module.ng.$compileProvider.directive.input.text text}, {@link api/angular.module.ng.$compileProvider.directive.input.number number}, {@link api/angular.module.ng.$compileProvider.directive.input.url url}, {@link api/angular.module.ng.$compileProvider.directive.input.email email}, {@link api/angular.module.ng.$compileProvider.directive.input.radio radio}, {@link api/angular.module.ng.$compileProvider.directive.input.checkbox checkbox}), as well as some directives for validation (`required`, `pattern`, `minlength`, `maxlength`, `min`, `max`).
+Angular provides basic implementation for most common html5 {@link api/ng.directive:input input}
+types: ({@link api/ng.directive:input.text text}, {@link api/ng.directive:input.number number}, {@link api/ng.directive:input.url url}, {@link api/ng.directive:input.email email}, {@link api/ng.directive:input.radio radio}, {@link api/ng.directive:input.checkbox checkbox}), as well as some directives for validation (`required`, `pattern`, `minlength`, `maxlength`, `min`, `max`).

-Defining your own validator can be done by defining your own directive which adds a custom validation function to the `ng-model` {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController controller}.
+Defining your own validator can be done by defining your own directive which adds a custom validation function to the `ngModel` {@link api/ng.directive:ngModel.NgModelController controller}.
 To get a hold of the controller the directive specifies a dependency as shown in the example below.
 The validation can occur in two places:

  * **Model to View update** -
-    Whenever the bound model changes, all functions in {@link   api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$formatters NgModelController#$formatters} array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$setValidity NgModelController#$setValidity}.
+    Whenever the bound model changes, all functions in {@link api/ng.directive:ngModel.NgModelController#$formatters NgModelController#$formatters} array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through {@link api/ng.directive:ngModel.NgModelController#$setValidity NgModelController#$setValidity}.

  * **View to Model update** -
-    In a similar way, whenever a user interacts with a control, the controll calls {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$setViewValue NgModelController#$setViewValue}.
-This in turn pipelines all functions in {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$parsers NgModelController#$parsers} array, so that each of these functions has an opportunity to convert the value and change validity state of the form control through {@link api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$setValidity NgModelController#$setValidity}.
+    In a similar way, whenever a user interacts with a control it calls {@link api/ng.directive:ngModel.NgModelController#$setViewValue NgModelController#$setViewValue}.
+This in turn pipelines all functions in the {@link api/ng.directive:ngModel.NgModelController#$parsers NgModelController#$parsers} array, so that each of these functions has an opportunity to convert the value and change validity state of the form control through {@link api/ng.directive:ngModel.NgModelController#$setValidity NgModelController#$setValidity}.

 In the following example we create two directives.

  * The first one is `integer` and it validates whether the input is a valid integer.
    For example `1.23` is an invalid value, since it contains a fraction.
-    Note, that we unshift the array instead of pushing.
+    Note that we unshift the array instead of pushing.
    This is because we want to be first parser and consume the control string value, as we need to execute the validation function before a conversion to number occurs.

  * The second directive is a `smart-float`.
    It parses both `1.2` and `1,2` into a valid float number `1.2`.
-    Note that, we can't use input type `number` here as HTML5 browsers would not allow the user to type what it would consider an invalid number such as `1,2`.
+    Note that we can't use input type `number` here as HTML5 browsers would not allow the user to type what it would consider an invalid number such as `1,2`.


 <doc:example module="form-example1">
@@ -231,7 +227,7 @@ In the following example we create two directives.
  </form>
 </div>

-<script type="text/javascript">
+<script>
  var app = angular.module('form-example1', []);

  var INTEGER_REGEXP = /^\-?\d*$/;
@@ -276,22 +272,22 @@ In the following example we create two directives.
 </doc:example>


-# Implementing custom form control (using ng-model)
-Angular implements all of the basic HTML form controls ({@link api/angular.module.ng.$compileProvider.directive.input input}, {@link api/angular.module.ng.$compileProvider.directive.select select}, {@link api/angular.module.ng.$compileProvider.directive.textarea textarea}), which should be sufficient for most cases.
+# Implementing custom form controls (using `ngModel`)
+Angular implements all of the basic HTML form controls ({@link api/ng.directive:input input}, {@link api/ng.directive:select select}, {@link api/ng.directive:textarea textarea}), which should be sufficient for most cases.
 However, if you need more flexibility, you can write your own form control as a directive.

-In order for custom control to work with `ng-model` and to achieve two-way data-binding it needs to:
+In order for custom control to work with `ngModel` and to achieve two-way data-binding it needs to:

-  - implement `render` method, which is responsible for rendering the data after it passed the {@link   api/angular.module.ng.$compileProvider.directive.ng-model.NgModelController#$formatters NgModelController#$formatters},
+  - implement `$render` method, which is responsible for rendering the data after it passed the {@link   api/ng.directive:ngModel.NgModelController#$formatters NgModelController#$formatters},
  - call `$setViewValue` method, whenever the user interacts with the control and model needs to be updated. This is usually done inside a DOM Event listener.

-See {@link api/angular.module.ng.$compileProvider.directive $compileProvider.directive} for more info.
+See {@link guide/directive $compileProvider.directive} for more info.

 The following example shows how to add two-way data-binding to contentEditable elements.

 <doc:example module="form-example2">
 <doc:source>
-<script type="text/javascript">
+<script>
  angular.module('form-example2', []).directive('contenteditable', function() {
    return {
      require: 'ngModel',
@@ -304,8 +300,8 @@ The following example shows how to add two-way data-binding to contentEditable e
        });

        // model -> view
-        ctrl.render = function(value) {
-          elm.html(value);
+        ctrl.$render = function() {
+          elm.html(ctrl.$viewValue);
        };

        // load init value from DOM
@@ -17,15 +17,15 @@ abstracted bits.
 **What level of support for i18n/l10n is currently in Angular?**

 Currently, Angular supports i18n/l10n for {@link
-http://docs.angularjs.org/#!/api/angular.module.ng.$filter.date datetime}, {@link
-http://docs.angularjs.org/#!/api/angular.module.ng.$filter.number number} and {@link
-http://docs.angularjs.org/#!/api/angular.module.ng.$filter.currency currency} filters.
+http://docs.angularjs.org/#!/api/ng.filter:date datetime}, {@link
+http://docs.angularjs.org/#!/api/ng.filter:number number} and {@link
+http://docs.angularjs.org/#!/api/ng.filter:currency currency} filters.

 Additionally, Angular supports localizable pluralization support provided by the {@link
-api/angular.module.ng.$compileProvider.directive.ng-pluralize ng-pluralize directive}.
+api/ng.directive:ngPluralize ngPluralize directive}.

 All localizable Angular components depend on locale-specific rule sets managed by the {@link
-api/angular.module.ng.$locale $locale service}.
+api/ng.$locale $locale service}.

 For readers who want to jump straight into examples, we have a few web pages that showcase how to
 use Angular filters with various locale rule sets. You can find these examples either on {@link
@@ -53,25 +53,25 @@ There are two approaches to providing locale rules to Angular:
 You can pre-bundle the desired locale file with Angular by concatenating the content of the
 locale-specific file to the end of `angular.js` or `angular.min.js` file.

-For example on *nix, to create a an angular.js file that contains localization rules for german
+For example on *nix, to create an angular.js file that contains localization rules for german
 locale, you can do the following:

-`cat angular.js i18n/angular-locale_de-ge.js > angular_de-ge.js`
+`cat angular.js i18n/angular-locale_de-de.js > angular_de-de.js`

-When the application containing `angular_de-ge.js` script instead of the generic angular.js script
+When the application containing `angular_de-de.js` script instead of the generic angular.js script
 starts, Angular is automatically pre-configured with localization rules for the german locale.

 **2. Including locale js script in index.html page**

 You can also include the locale specific js file in the index.html page. For example, if one client
-requires German locale, you would serve index_de-ge.html which will look something like this:
+requires German locale, you would serve index_de-de.html which will look something like this:

 <pre>
 <html ng-app>
 <head>
 ….
   <script src="angular.js"></script>
-   <script src="i18n/angular-locale_de-ge.js"></script>
+   <script src="i18n/angular-locale_de-de.js"></script>
 ….
 </head>
 </html>
@@ -90,8 +90,8 @@ because an extra script needs to be loaded.

 **Currency symbol "gotcha"**

-Angular's {@link http://docs.angularjs.org/#!/api/angular.module.ng.$filter.currency currency filter} allows
-you to use the default currency symbol from the {@link api/angular.module.ng.$locale locale service},
+Angular's {@link http://docs.angularjs.org/#!/api/ng.filter:currency currency filter} allows
+you to use the default currency symbol from the {@link api/ng.$locale locale service},
 or you can provide the filter with a custom currency symbol. If your app will be used only in one
 locale, it is fine to rely on the default currency symbol. However, if you anticipate that viewers
 in other locales might use your app, you should provide your own currency symbol to make sure the
@@ -104,7 +104,7 @@ browser will specify the locale as ja, and the balance of '¥1000.00' will be sh
 will really upset your client.

 In this case, you need to override the default currency symbol by providing the {@link
-http://docs.angularjs.org/#!/api/angular.module.ng.$filter.currency currency filter} with a currency symbol as
+http://docs.angularjs.org/#!/api/ng.filter:currency currency filter} with a currency symbol as
 a parameter when you configure the filter, for example, {{ 1000 | currency:"USD$"}}. This way,
 Angular will always show a balance of 'USD$1000' and disregard any locale changes.

@@ -5,43 +5,68 @@
 # Overview

 This document describes the Internet Explorer (IE) idiosyncrasies when dealing with custom HTML
-attributes and tags. Read this document if you are planning on deploying your angular application
+attributes and tags. Read this document if you are planning on deploying your Angular application
 on IE v8.0 or earlier.

 # Short Version

-To make your angular application work on IE please make sure that:
+To make your Angular application work on IE please make sure that:

-  1. you **do not** use custom element tags such as `<ng:view>` (use the attribute version `<div
-  ng-view>` instead), or
+  1. You polyfill JSON.stringify if necessary (IE7 will need this). You can use
+     [JSON2](https://github.com/douglascrockford/JSON-js) or
+     [JSON3](http://bestiejs.github.com/json3/) polyfills for this.
+     <pre>
+       <!doctype html>
+       <html xmlns:ng="http://angularjs.org">
+         <head>
+           <!--[if lte IE 8]>
+             <script src="/path/to/json2.js"></script>
+           <![endif]-->
+         </head>
+         <body>
+           ...
+         </body>
+       </html>
+     </pre>

-  2. if you **do use** custom element tags, then you must take these steps to make IE happy:
+  2. add `id="ng-app"` to the root element in conjunction with `ng-app` attribute
+     <pre>
+       <!doctype html>
+       <html xmlns:ng="http://angularjs.org" id="ng-app" ng-app="optionalModuleName">
+         ...
+       </html>
+     </pre>

-<pre>
-  <html xmlns:ng="http://angularjs.org">
-    <head>
-      <!--[if lte IE 8]>
-        <script>
-          document.createElement('ng-include');
-          document.createElement('ng-pluralize');
-          document.createElement('ng-view');
-          
-          // Optionally these for CSS
-          document.createElement('ng:include');
-          document.createElement('ng:pluralize');
-          document.createElement('ng:view');
-        </script>
-      <![endif]-->
-    </head>
-    <body>
-      ...
-    </body>
-  </html>
-</pre>
+  3. you **do not** use custom element tags such as `<ng:view>` (use the attribute version
+     `<div ng-view>` instead), or
+
+  4. if you **do use** custom element tags, then you must take these steps to make IE happy:
+     <pre>
+       <!doctype html>
+       <html xmlns:ng="http://angularjs.org" id="ng-app" ng-app="optionalModuleName">
+         <head>
+           <!--[if lte IE 8]>
+             <script>
+               document.createElement('ng-include');
+               document.createElement('ng-pluralize');
+               document.createElement('ng-view');
+     
+               // Optionally these for CSS
+               document.createElement('ng:include');
+               document.createElement('ng:pluralize');
+               document.createElement('ng:view');
+             </script>
+           <![endif]-->
+         </head>
+         <body>
+           ...
+         </body>
+       </html>
+     </pre>

 The **important** parts are:

-  * `xmlns:ng` - *namespace* - you need one namespace for each custom tay you are planning on
+  * `xmlns:ng` - *namespace* - you need one namespace for each custom tag you are planning on
    using.

  * `document.createElement(yourTagName)` - *creation of custom tag names* - Since this is an
@@ -52,7 +77,7 @@ The **important** parts are:

 # Long Version

-IE has an issues with element tag names which are not standard HTML tag names. These fall into two
+IE has issues with element tag names which are not standard HTML tag names. These fall into two
 categories, and each category has its own fix.

  * If the tag name starts with `my:` prefix than it is considered an XML namespace and must
@@ -61,13 +86,13 @@ categories, and each category has its own fix.
  * If the tag has no `:` but it is not a standard HTML tag, then it must be pre-created using
    `document.createElement('my-tag')`

-  * If you have are planning on styling the custom tag with CSS selectors, then it must be
+  * If you are planning on styling the custom tag with CSS selectors, then it must be
    pre-created using `document.createElement('my-tag')` regardless of XML namespace.


 ## The Good News

-The good news is that these restrictions only apply to element tag names, and not to element 
+The good news is that these restrictions only apply to element tag names, and not to element
 attribute names. So this requires no special handling in IE: `<div my-tag your:tag></div>`.


@@ -84,7 +109,7 @@ result):
  </html>
 </pre>

-It should pares into the following DOM:
+It should parse into the following DOM:

 <pre>
 #document
@@ -118,12 +143,12 @@ In IE, the behavior is that the `BODY` element has three children:

  3. A corrupt self closing `/mytag`. This is corrupt since element names are not allowed to have
  the `/` character. Furthermore this closing element should not be part of the DOM since it is
-  only used to delimitate the structure of the DOM.
+  only used to delineate the structure of the DOM.


 ## CSS Styling of Custom Tag Names

-The to make CSS selector work with custom elements the custom element name must be shived with the
+To make CSS selectors work with custom elements, the custom element name must be pre-created with 
 `document.createElement('my-tag')` regardless of XML namespace.

 <pre>
@@ -133,7 +158,7 @@ The to make CSS selector work with custom elements the custom element name must
        <script>
          // needed to make ng-include parse properly
          document.createElement('ng-include');
-          
+
          // needed to enable CSS reference
          document.createElement('ng:view');
        </script>
@@ -2,7 +2,7 @@
@name Developer Guide
@description

-Welcome to the angular Developer Guide.  If you are here to learn the details of how to use angular
+Welcome to the angular Developer Guide. If you are here to learn the details of how to use angular
 to develop web apps, you've come to the right place.

 If you are completely or relatively unfamiliar with angular, you may want to check out one or both
@@ -10,44 +10,3 @@ of the following documents before returning here to the Developer Guide:

 * {@link misc/started Getting Started}
 * {@link tutorial/index Angular Tutorial}
-
-<hr>
-
-## {@link dev_guide.overview Overview of Angular}
-
-## {@link dev_guide.bootstrap Initializing Angular}
-
-* {@link dev_guide.bootstrap.auto_bootstrap Understanding Automatic Initialization}
-* {@link dev_guide.bootstrap.manual_bootstrap Understanding Manual Initialization}
-
-## {@link dev_guide.mvc About MVC in Angular}
-
-* {@link dev_guide.mvc.understanding_model Understanding the Model Component}
-* {@link dev_guide.mvc.understanding_controller Understanding the Controller Component}
-* {@link dev_guide.mvc.understanding_view Understanding the View Component}
-
-## {@link dev_guide.scopes Angular Scope Objects}
-
-* {@link dev_guide.scopes.understanding_scopes Understanding Angular Scope Objects}
-* {@link dev_guide.scopes.internals Angular Scope Internals}
-
-## {@link dev_guide.compiler Angular HTML Compiler}
-
-* {@link api/angular.module.ng.$compileProvider.directive Understanding Angular Directives}
-
-## {@link dev_guide.templates Angular Templates}
-
-* {@link dev_guide.templates.filters Understanding Angular Filters}
-* {@link dev_guide.forms Understanding Angular Forms}
-
-## {@link dev_guide.services Angular Services}
-
-* {@link dev_guide.services.understanding_services Understanding Angular Services}
-* {@link dev_guide.services.creating_services Creating Angular Services}
-* {@link dev_guide.services.managing_dependencies Managing Service Dependencies}
-* {@link dev_guide.services.testing_services Testing Angular Services}
-
-## {@link dev_guide.di About Dependency Injection}
-
-* {@link dev_guide.di.understanding_di Understanding DI in Angular}
-* {@link dev_guide.di.using_di_controllers Using DI in Controllers}
@@ -3,40 +3,40 @@
@description

 Angular is pure client-side technology, written entirely in JavaScript. It works with the
-long-established technologies of the web (HTML, CSS, and JavaScript) to make the development of web
-apps easier and faster than ever before.
+long-established technologies of the web (HTML, CSS, and JavaScript) to make the development of
+web apps easier and faster than ever before.

-One important way that angular simplifies web development is by increasing the level of abstraction
+One important way that Angular simplifies web development is by increasing the level of abstraction
 between the developer and most low-level web app development tasks. Angular automatically takes
 care of many of these tasks, including:

-* DOM Manipulation
-* Setting Up Listeners and Notifiers
-* Input Validation
+  * DOM Manipulation
+  * Setting Up Listeners and Notifiers
+  * Input Validation

-Because angular handles much of the work involved in these tasks, developers can concentrate more
+Because Angular handles much of the work involved in these tasks, developers can concentrate more
 on application logic and less on repetitive, error-prone, lower-level coding.

-At the same time that angular simplifies the development of web apps, it brings relatively
+At the same time that Angular simplifies the development of web apps, it brings relatively
 sophisticated techniques to the client-side, including:

-* Separation of data, application logic, and presentation components
-* Data Binding between data and presentation components
-* Services (common web app operations, implemented as substitutable objects)
-* Dependency Injection (used primarily for wiring together services)
-* An extensible HTML compiler (written entirely in JavaScript)
-* Ease of Testing
+  * Separation of data, application logic, and presentation components
+  * Data Binding between data and presentation components
+  * Services (common web app operations, implemented as substitutable objects)
+  * Dependency Injection (used primarily for wiring together services)
+  * An extensible HTML compiler (written entirely in JavaScript)
+  * Ease of Testing

 These techniques have been for the most part absent from the client-side for far too long.

 ## Single-page / Round-trip Applications

-You can use angular to develop both single-page and round-trip apps, but angular is designed
+You can use Angular to develop both single-page and round-trip apps, but Angular is designed
 primarily for developing single-page apps. Angular supports browser history, forward and back
 buttons, and bookmarking in single-page apps.

-You normally wouldn't want to load angular with every page change, as would be the case with using
-angular in a round-trip app. However, it would make sense to do so if you were adding a subset of
-angular's features (for example, templates to leverage angular's data-binding feature) to an
+You normally wouldn't want to load Angular with every page change, as would be the case with using
+Angular in a round-trip app. However, it would make sense to do so if you were adding a subset of
+Angular's features (for example, templates to leverage angular's data-binding feature) to an
 existing round-trip app. You might follow this course of action if you were migrating an older app
-to a single-page angular app.
+to a single-page Angular app.
@@ -5,9 +5,8 @@
 # What is a Module?

 Most applications have a main method which instantiates, wires, and bootstraps the application.
-Angular apps don't have a main method, instead the modules serves the purpose of declaratively
-specifying how an application should be bootstrapped. There are several advantages to this
-approach:
+Angular apps don't have a main method. Instead modules declaratively specify how an application
+should be bootstrapped. There are several advantages to this approach:

  * The process is more declarative which is easier to understand
  * In unit-testing there is no need to load all modules, which may aid in writing unit-tests.
@@ -19,7 +18,7 @@ approach:

 # The Basics

-Ok, I'm in a hurry how do i get a Hello World module working?
+Ok, I'm in a hurry. How do I get a Hello World module working?

 Important things to notice:

@@ -27,15 +26,15 @@ Important things to notice:
  * Notice the reference to the `myApp` module in the `<html ng-app="myApp">`, it is what
    bootstraps the app using your module.

-<doc:example module='simpleApp'>
+<doc:example module='myApp'>
  <doc:source>
    <script>
      // declare a module
-      var simpleAppModule = angular.module('simpleApp', []);
+      var myAppModule = angular.module('myApp', []);

      // configure the module.
      // in this example we will create a greeting filter
-      simpleAppModule.filter('greet', function() {
+      myAppModule.filter('greet', function() {
       return function(name) {
          return 'Hello, ' + name + '!';
        };
@@ -62,9 +61,9 @@ that you break your application to multiple modules like this:
    initialization code.

 The reason for this breakup is that in your tests, it is often necessary to ignore the
-initialization code, which tends to be difficult to test. By putting it into separate module it
+initialization code, which tends to be difficult to test. By putting it into a separate module it
 can be easily ignored in tests. The tests can also be more focused by only loading the modules
-which are relevant to tests.
+that are relevant to tests.

 The above is only a suggestion, so feel free to tailor it to your needs.

@@ -139,7 +138,7 @@ angular.module('myModule', []).
    // This is an example of a run block.
    // You can have as many of these as you want.
    // You can only inject instances (not Providers)
-    // int the run blocks
+    // into the run blocks
  });
 </pre>

@@ -159,9 +158,9 @@ angular.module('myModule', []).

 angular.module('myModule', []).
  config(function($provide, $compileProvider, $filterProvider) {
-    $provide.value('a', 123)
-    $provide.factory('a', function() { return 123; })
-    $compileProvider.directive('directiveName', ...).
+    $provide.value('a', 123);
+    $provide.factory('a', function() { return 123; });
+    $compileProvider.directive('directiveName', ...);
    $filterProvider.register('filterName', ...);
  });
 </pre>
@@ -181,7 +180,7 @@ ignored in the unit-tests.

 Modules can list other modules as their dependencies. Depending on a module implies that required
 module needs to be loaded before the requiring module is loaded. In other words the configuration
-blocks of the required modules execute before the configuration blocks or the requiring module.
+blocks of the required modules execute before the configuration blocks of the requiring module.
 The same is true for the run blocks. Each module can only be loaded once, even if multiple other
 modules require it.

@@ -190,12 +189,30 @@ modules require it.
 Modules are a way of managing $injector configuration, and have nothing to do with loading of
 scripts into a VM. There are existing projects which deal with script loading, which may be used
 with Angular. Because modules do nothing at load time they can be loaded into the VM in any order
-and thus script loaders can take advantage of this property and paralyze the loading process.
+and thus script loaders can take advantage of this property and parallelize the loading process.

+## Creation versus Retrieval
+
+Beware that using `angular.module('myModule', [])` will create the module `myModule` and overwrite any
+existing module named `myModule`. Use `angular.module('myModule')` to retrieve an existing module.
+
+<pre>
+  var myModule = angular.module('myModule', []);
+  
+  // add some directives and services
+  myModule.service('myService', ...);
+  myModule.directive('myDirective', ...);
+
+  // overwrites both myService and myDirective by creating a new module
+  var myModule = angular.module('myModule', []);
+
+  // throws an error because myOtherModule has yet to be defined
+  var myModule = angular.module('myOtherModule');
+</pre>

 # Unit Testing

-In its simplest form a unit-test is a way of instantiating a subset of the application in test and
+In its simplest form a unit test is a way of instantiating a subset of the application in test and
 then applying a stimulus to it. It is important to realize that each module can only be loaded
 once per injector. Typically an app has only one injector. But in tests, each test has its own
 injector, which means that the modules are loaded multiple times per VM. Properly structured
@@ -223,8 +240,8 @@ In all of these examples we are going to assume this module definition:
 Let's write some tests:
 <pre>
 describe('myApp', function() {
-  // load the application relevant modules then load a special
-  // test module which overrides the $window with mock version,
+  // load the relevant application modules then load a special
+  // test module which overrides the $window with a mock version,
  // so that calling window.alert() will not block the test
  // runner with a real alert box. This is an example of overriding
  // configuration information in tests.
@@ -232,7 +249,7 @@ describe('myApp', function() {
    $provide.value('$window', {
      alert: jasmine.createSpy('alert')
    });
-  });
+  }));

  // The inject() will create the injector and inject the greet and
  // $window into the tests. The test need not concern itself with
@@ -251,7 +268,7 @@ describe('myApp', function() {
    });
    inject(function(greet) {
      greet('World');
-      expect(alertSpy).toHaveBeenCalledWith('World');
+      expect(alertSpy).toHaveBeenCalledWith('Hello World!');
    });
  });
 });
@@ -0,0 +1,207 @@
+@ngdoc overview
+@name Developer Guide: Overview
+@description
+
+
+# What Is Angular?
+
+AngularJS is a structural framework for dynamic web apps. It lets you use HTML as your template
+language and lets you extend HTML's syntax to express your application's components clearly and
+succinctly. Out of the box, it eliminates much of the code you currently write through data
+binding and dependency injection. And it all happens in JavaScript within the browser, making it
+an ideal partner with any server technology.
+
+Angular is what HTML would have been had it been designed for applications. HTML is a great
+declarative language for static documents. It does not contain much in the way of creating
+applications, and as a result building web applications is an exercise in *what do I have to do
+to trick the browser into doing what I want.*
+
+The impedance mismatch between dynamic applications and static documents is often solved with:
+
+  * **a library** - a collection of functions which are useful when writing web apps. Your code is
+    in charge and it calls into the library when it sees fit. E.g., `jQuery`.
+  * **frameworks** - a particular implementation of a web application, where your code fills in
+    the details. The framework is in charge and it calls into your code when it needs something
+    app specific. E.g., `knockout`, `ember`, etc.
+
+
+Angular takes another approach. It attempts to minimize the impedance mismatch between document
+centric HTML and what an application needs by creating new HTML constructs. Angular teaches the
+browser new syntax through a construct we call directives. Examples include:
+
+  * Data binding, as in `{{}}`.
+  * DOM control structures for repeating/hiding DOM fragments.
+  * Support for forms and form validation.
+  * Attaching code-behind to DOM elements.
+  * Grouping of HTML into reusable components.
+
+
+
+## A complete client-side solution
+
+Angular is not a single piece in the overall puzzle of building the client-side of a web
+application. It handles all of the DOM and AJAX glue code you once wrote by hand and puts it in a
+well-defined structure. This makes Angular opinionated about how a CRUD application should be
+built. But while it is opinionated, it also tries to make sure that its opinion is just a
+starting point you can easily change. Angular comes with the following out-of-the-box:
+
+  * Everything you need to build a CRUD app in a cohesive set: data-binding, basic templating
+    directives, form validation, routing, deep-linking, reusable components, dependency injection.
+  * Testability story: unit-testing, end-to-end testing, mocks, test harnesses.
+  * Seed application with directory layout and test scripts as a starting point.
+
+
+## Angular Sweet Spot
+
+Angular simplifies application development by presenting a higher level of abstraction to the
+developer. Like any abstraction, it comes at a cost of flexibility. In other words not every app
+is a good fit for Angular. Angular was built for the CRUD application in mind. Luckily CRUD
+applications represent the majority of web applications. But to understand what Angular is
+good at one also has to understand when an app is not a good fit for Angular.
+
+Games and GUI editors are examples of applications with intensive and tricky DOM manipulation.
+These kinds of apps are different from CRUD apps, and as a result are probably not a good fit for Angular.
+In these cases it may be better to use a library with a lower level of abstraction, such as `jQuery`.
+
+
+# An Introductory Angular Example
+
+Below is a typical CRUD application which contains a form. The form values are validated, and
+are used to compute the total, which is formatted to a particular locale. These are some common
+concepts which the application developer may face:
+
+  * attaching data-model to the UI.
+  * writing, reading and validating user input.
+  * computing new values based on the model.
+  * formatting output in a user specific locale.
+
+<example>
+  <file name="script.js">
+    function InvoiceCntl($scope) {
+      $scope.qty = 1;
+      $scope.cost = 19.95;
+    }
+  </file>
+  <file name="index.html">
+    <div ng-controller="InvoiceCntl">
+      <b>Invoice:</b>
+      <br>
+      <br>
+      <table>
+       <tr><td>Quantity</td><td>Cost</td></tr>
+       <tr>
+         <td><input type="number" ng-pattern="/\d+/" step="1" min="0" ng-model="qty" required ></td>
+         <td><input type="number" ng-model="cost" required ></td>
+       </tr>
+      </table>
+      <hr>
+      <b>Total:</b> {{qty * cost | currency}}
+    </div>
+  </file>
+  <file name="scenario.js">
+    it('should show of angular binding', function() {
+      expect(binding('qty * cost')).toEqual('$19.95');
+      input('qty').enter('2');
+      input('cost').enter('5.00');
+      expect(binding('qty * cost')).toEqual('$10.00');
+    });
+  </file>
+</example>
+
+Try out the Live Preview above, and then let's walk through the example and describe what's going
+on.
+
+In the `<html>` tag, we specify that it is an Angular
+application with the `ng-app` directive. The `ng-app` will cause Angular to {@link
+bootstrap auto initialize} your application.
+
+    <html ng-app>
+
+We load Angular using the  `<script>` tag:
+
+    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/?.?.?/angular.min.js"></script>
+
+From the `ng-model` attribute of the `<input>` tags, Angular automatically sets up two-way data
+binding, and we also demonstrate some easy input validation:
+
+    Quantity: <input type="number" ng-pattern="/\d+/" step="1" min="0" ng-model="qty" required >
+    Cost: <input type="number" ng-model="cost" required >
+
+These input widgets look normal enough, but consider these points:
+
+  * When this page loaded, Angular bound the names of the input widgets (`qty` and `cost`) to
+    variables of the same name. Think of those variables as the "Model" component of the
+    Model-View-Controller design pattern.
+  * Note that the HTML widget {@link api/ng.directive:input input}
+    has special powers. The input invalidates itself by turning red when you enter invalid data or
+    leave the input fields blank. These new widget behaviors make it easier to implement field
+    validation common in CRUD applications.
+
+And finally, the mysterious `{{ double curly braces }}`:
+
+         Total: {{qty * cost | currency}}
+
+This notation, `{{ _expression_ }}`, is Angular markup for data-binding. The expression itself can
+be a combination of both an expression and a {@link dev_guide.templates.filters filter}: `{{
+expression | filter }}`. Angular provides filters for formatting display data.
+
+In the example above, the expression in double-curly braces directs Angular to "bind the data we
+got from the input widgets to the display, multiply them together, and format the resulting number
+into output that looks like money."
+
+Notice that we achieved this application behavior not by calling Angular methods, nor by
+implementing application specific behavior as a framework. We achieved the behavior because the
+browser behaved more in line with what is needed for a dynamic web application rather than what is
+needed for a static document. Angular has lowered the impedance mismatch to the point where no
+library/framework calls are needed.
+
+
+# The Zen of Angular
+
+Angular is built around the belief that declarative code is better than imperative when it comes
+to building UIs and wiring software components together, while imperative code is excellent for
+expressing business logic.
+
+
+  * It is a very good idea to decouple DOM manipulation from app logic. This dramatically improves
+    the testability of the code.
+  * It is a really, _really_ good idea to regard app testing as equal in importance to app
+    writing. Testing difficulty is dramatically affected by the way the code is structured.
+  * It is an excellent idea to decouple the client side of an app from the server side. This
+    allows development work to progress in parallel, and allows for reuse of both sides.
+  * It is very helpful indeed if the framework guides developers through the entire journey of
+    building an app: from designing the UI, through writing the business logic, to testing.
+  * It is always good to make common tasks trivial and difficult tasks possible.
+
+
+
+Angular frees you from the following pains:
+
+  * **Registering callbacks:** Registering callbacks clutters your code, making it hard to see the
+    forest for the trees. Removing common boilerplate code such as callbacks is a good thing. It
+    vastly reduces the amount of JavaScript coding _you_ have to do, and it makes it easier to see
+    what your application does.
+  * **Manipulating HTML DOM programmatically:** Manipulating HTML DOM is a cornerstone of AJAX
+    applications, but it's cumbersome and error-prone. By declaratively describing how the UI
+    should change as your application state changes, you are freed from low level DOM manipulation
+    tasks. Most applications written with Angular never have to programmatically manipulate the
+    DOM, although you can if you want to.
+  * **Marshaling data to and from the UI:** CRUD operations make up the majority of AJAX
+    applications. The flow of marshaling data from the server to an internal object to an HTML
+    form, allowing users to modify the form, validating the form, displaying validation errors,
+    returning to an internal model, and then back to the server, creates a lot of boilerplate
+    code. Angular eliminates almost all of this boilerplate, leaving code that describes the
+    overall flow of the application rather than all of the implementation details.
+  * **Writing tons of initialization code just to get started:** Typically you need to write a lot
+    of plumbing just to get a basic "Hello World" AJAX app working. With Angular you can bootstrap
+    your app easily using services, which are auto-injected into your application in a {@link
+    http://code.google.com/p/google-guice/ Guice}-like dependency-injection style. This allows you
+    to get started developing features quickly. As a bonus, you get full control over the
+    initialization process in automated tests.
+
+
+# Watch a Presentation About Angular
+
+Here is a presentation on Angular from May 2012. The {@link http://mhevery.github.io/angular-demo-slides/index.html#/list corresponding slides} are also available.
+
+<iframe width="560" height="315" src="http://www.youtube.com/embed/bfrn5VNpwsg" frameborder="0" allowfullscreen></iframe>
@@ -0,0 +1,331 @@
+@ngdoc overview
+@name Developer Guide: Scopes
+@description
+
+# What are Scopes?
+
+{@link api/ng.$rootScope.Scope scope} is an object that refers to the application
+model. It is an execution context for {@link expression expressions}. Scopes are
+arranged in hierarchical structure which mimic the DOM structure of the application. Scopes can
+watch {@link guide/expression expressions} and propagate events.
+
+## Scope characteristics
+
+  - Scopes provide APIs ({@link api/ng.$rootScope.Scope#$watch $watch}) to observe
+    model mutations.
+
+  - Scopes provide APIs ({@link api/ng.$rootScope.Scope#$apply $apply}) to
+    propagate any model changes through the system into the view from outside of the "Angular
+    realm" (controllers, services, Angular event handlers).
+
+  - Scopes can be nested to isolate application components while providing access to shared model
+    properties. A scope (prototypically) inherits properties from its parent scope.
+
+  - Scopes provide context against which {@link guide/expression expressions} are evaluated. For
+    example `{{username}}` expression is meaningless, unless it is evaluated against a specific
+    scope which defines the `username` property.
+
+## Scope as Data-Model
+
+Scope is the glue between application controller and the view. During the template {@link compiler
+linking} phase the {@link api/ng.$compileProvider#directive directives} set up
+{@link api/ng.$rootScope.Scope#$watch `$watch`} expressions on the scope. The
+`$watch` allows the directives to be notified of property changes, which allows the directive to
+render the updated value to the DOM.
+
+Both controllers and directives have reference to the scope, but not to each other. This
+arrangement isolates the controller from the directive as well as from DOM. This is an important
+point since it makes the controllers view agnostic, which greatly improves the testing story of
+the applications.
+
+<example>
+  <file name="script.js">
+    function MyController($scope) {
+      $scope.username = 'World';
+
+      $scope.sayHello = function() {
+        $scope.greeting = 'Hello ' + $scope.username + '!';
+      };
+    }
+  </file>
+  <file name="index.html">
+    <div ng-controller="MyController">
+      Your name:
+        <input type="text" ng-model="username">
+        <button ng-click='sayHello()'>greet</button>
+      <hr>
+      {{greeting}}
+    </div>
+  </file>
+</example>
+
+In the above example notice that the `MyController` assigns `World` to the `username` property of
+the scope. The scope then notifies the `input` of the assignment, which then renders the input
+with username pre-filled. This demonstrates how a controller can write data into the scope.
+
+Similarly the controller can assign behavior to scope as seen by the `sayHello` method, which is
+invoked when the user clicks on the 'greet' button. The `sayHello` method can read the `username`
+property and create a `greeting` property. This demonstrates that the properties on scope update
+automatically when they are bound to HTML input widgets.
+
+Logically the rendering of `{{greeting}}` involves:
+
+  * retrieval of the scope associated with DOM node where `{{greeting}}` is defined in template.
+    In this example this is the same scope as the scope which was passed into `MyController`. (We
+    will discuss scope hierarchies later.)
+
+  * Evaluate the `greeting` {@link guide/expression expression} against the scope retrieved above,
+    and assign the result to the text of the enclosing DOM element.
+
+
+You can think of the scope and its properties as the data which is used to render the view. The
+scope is the single source-of-truth for all things view related.
+
+From a testability point of view, the separation of the controller and the view is desirable, because it allows us
+to test the behavior without being distracted by the rendering details.
+
+<pre>
+  it('should say hello', function() {
+    var scopeMock = {};
+    var cntl = new MyController(scopeMock);
+
+    // Assert that username is pre-filled
+    expect(scopeMock.username).toEqual('World');
+
+    // Assert that we read new username and greet
+    scopeMock.username = 'angular';
+    scopeMock.sayHello();
+    expect(scopeMock.greeting).toEqual('Hello angular!');
+  });
+</pre>
+
+
+## Scope Hierarchies
+
+Each Angular application has exactly one {@link api/ng.$rootScope root scope}, but
+may have several child scopes.
+
+The application can have multiple scopes, because some {@link guide/directive directives} create
+new child scopes (refer to directive documentation to see which directives create new scopes).
+When new scopes are created, they are added as children of their parent scope. This creates a tree
+structure which parallels the DOM where they're attached
+
+When Angular evaluates `{{username}}`, it first looks at the scope associated with the given
+element for the `username` property. If no such property is found, it searches the parent scope
+and so on until the root scope is reached. In JavaScript this behavior is known as prototypical
+inheritance, and child scopes prototypically inherit from their parents.
+
+This example illustrates scopes in application, and prototypical inheritance of properties.
+
+<example>
+  <file name="style.css">
+    /* remove .doc-example-live in jsfiddle */
+    .doc-example-live .ng-scope {
+      border: 1px dashed red;
+    }
+  </file>
+  <file name="script.js">
+    function EmployeeController($scope) {
+      $scope.department = 'Engineering';
+      $scope.employee = {
+        name: 'Joe the Manager',
+        reports: [
+          {name: 'John Smith'},
+          {name: 'Mary Run'}
+        ]
+      };
+    }
+  </file>
+  <file name="index.html">
+    <div ng-controller="EmployeeController">
+      Manager: {{employee.name}} [ {{department}} ]<br>
+      Reports:
+        <ul>
+          <li ng-repeat="employee in employee.reports">
+            {{employee.name}} [ {{department}} ]
+          </li>
+        </ul>
+      <hr>
+      {{greeting}}
+    </div>
+  </file>
+</example>
+
+Notice that Angular automatically places `ng-scope` class on elements where scopes are
+attached. The `<style>` definition in this example highlights in red the new scope locations. The
+child scopes are necessary because the repeater evaluates `{{employee.name}}` expression, but
+depending on which scope the expression is evaluated it produces different result. Similarly the
+evaluation of `{{department}}` prototypically inherits from root scope, as it is the only place
+where the `department` property is defined.
+
+
+## Retrieving Scopes from the DOM.
+
+Scopes are attached to the DOM as `$scope` data property, and can be retrieved for debugging
+purposes. (It is unlikely that one would need to retrieve scopes in this way inside the
+application.) The location where the root scope is attached to the DOM is defined by the location
+of {@link api/ng.directive:ngApp `ng-app`} directive. Typically
+`ng-app` is placed on the `<html>` element, but it can be placed on other elements as well, if,
+for example, only a portion of the view needs to be controlled by Angular.
+
+To examine the scope in the debugger:
+
+  1. right click on the element of interest in your browser and select 'inspect element'. You
+  should see the browser debugger with the element you clicked on highlighted.
+
+  2. The debugger allows you to access the currently selected element in the console as `$0`
+    variable.
+
+  3. To retrieve the associated scope in console execute: `angular.element($0).scope()`
+
+
+## Scope Events Propagation
+
+Scopes can propagate events in similar fashion to DOM events. The event can be {@link
+api/ng.$rootScope.Scope#$broadcast broadcasted} to the scope children or {@link
+api/ng.$rootScope.Scope#$emit emitted} to scope parents.
+
+<example>
+  <file name="script.js">
+    function EventController($scope) {
+      $scope.count = 0;
+      $scope.$on('MyEvent', function() {
+        $scope.count++;
+      });
+    }
+  </file>
+  <file name="index.html">
+    <div ng-controller="EventController">
+      Root scope <tt>MyEvent</tt> count: {{count}}
+      <ul>
+        <li ng-repeat="i in [1]" ng-controller="EventController">
+          <button ng-click="$emit('MyEvent')">$emit('MyEvent')</button>
+          <button ng-click="$broadcast('MyEvent')">$broadcast('MyEvent')</button>
+          <br>
+          Middle scope <tt>MyEvent</tt> count: {{count}}
+          <ul>
+            <li ng-repeat="item in [1, 2]" ng-controller="EventController">
+              Leaf scope <tt>MyEvent</tt> count: {{count}}
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </div>
+  </file>
+</example>
+
+
+
+## Scope Life Cycle
+
+The normal flow of a browser receiving an event is that it executes a corresponding JavaScript
+callback. Once the callback completes the browser re-renders the DOM and returns to waiting for
+more events.
+
+When the browser calls into JavaScript the code executes outside the Angular execution context,
+which means that Angular is unaware of model modifications. To properly process model
+modifications the execution has to enter the Angular execution context using the {@link
+api/ng.$rootScope.Scope#$apply `$apply`} method. Only model modifications which
+execute inside the `$apply` method will be properly accounted for by Angular. For example if a
+directive listens on DOM events, such as {@link
+api/ng.directive:ngClick `ng-click`} it must evaluate the
+expression inside the `$apply` method.
+
+After evaluating the expression, the `$apply` method performs a {@link
+api/ng.$rootScope.Scope#$digest `$digest`}. In the $digest phase the scope examines all
+of the `$watch` expressions and compares them with the previous value. This dirty checking is done
+asynchronously. This means that assignment such as `$scope.username="angular"` will not
+immediately cause a `$watch` to be notified, instead the `$watch` notification is delayed until
+the `$digest` phase. This delay is desirable, since it coalesces multiple model updates into one
+`$watch` notification as well as it guarantees that during the `$watch` notification no other
+`$watch`es are running. If a `$watch` changes the value of the model, it will force additional
+`$digest` cycle.
+
+  1. **Creation**
+
+     The {@link api/ng.$rootScope root scope} is created during the application
+     bootstrap by the {@link api/AUTO.$injector $injector}. During template
+     linking, some directives create new child scopes.
+
+  2. **Watcher registration**
+
+     During template linking directives register {@link
+     api/ng.$rootScope.Scope#$watch watches} on the scope. These watches will be
+     used to propagate model values to the DOM.
+
+  3. **Model mutation**
+
+     For mutations to be properly observed, you should make them only within the {@link
+     api/ng.$rootScope.Scope#$apply scope.$apply()}. (Angular APIs do this
+     implicitly, so no extra `$apply` call is needed when doing synchronous work in controllers,
+     or asynchronous work with {@link api/ng.$http $http} or {@link
+     api/ng.$timeout $timeout} services.
+
+  4. **Mutation observation**
+
+     At the end `$apply`, Angular performs a {@link api/ng.$rootScope.Scope#$digest
+     $digest} cycle on the root scope, which then propagates throughout all child scopes. During
+     the `$digest` cycle, all `$watch`ed expressions or functions are checked for model mutation
+     and if a mutation is detected, the `$watch` listener is called.
+
+  5. **Scope destruction**
+
+     When child scopes are no longer needed, it is the responsibility of the child scope creator
+     to destroy them via {@link api/ng.$rootScope.Scope#$destroy scope.$destroy()}
+     API. This will stop propagation of `$digest` calls into the child scope and allow for memory
+     used by the child scope models to be reclaimed by the garbage collector.
+
+
+### Scopes and Directives
+
+During the compilation phase, the {@link compiler compiler} matches {@link
+api/ng.$compileProvider#directive directives} against the DOM template. The directives
+usually fall into one of two categories:
+
+  - Observing {@link api/ng.$compileProvider#directive directives}, such as
+    double-curly expressions `{{expression}}`, register listeners using the {@link
+    api/ng.$rootScope.Scope#$watch $watch()} method. This type of directive needs
+    to be notified whenever the expression changes so that it can update the view.
+
+  - Listener directives, such as {@link api/ng.directive:ngClick
+    ng-click}, register a listener with the DOM. When the DOM listener fires, the directive
+    executes the associated expression and updates the view using the {@link
+    api/ng.$rootScope.Scope#$apply $apply()} method.
+
+When an external event (such as a user action, timer or XHR) is received, the associated {@link
+expression expression} must be applied to the scope through the {@link
+api/ng.$rootScope.Scope#$apply $apply()} method so that all listeners are updated
+correctly.
+
+### Directives that Create Scopes
+
+In most cases, {@link api/ng.$compileProvider#directive directives} and scopes interact
+but do not create new instances of scope. However, some directives, such as {@link
+api/ng.directive:ngController ng-controller} and {@link
+api/ng.directive:ngRepeat ng-repeat}, create new child scopes
+and attach the child scope to the corresponding DOM element. You can retrieve a scope for any DOM
+element by using an `angular.element(aDomElement).scope()` method call.
+
+### Controllers and Scopes
+
+Scopes and controllers interact with each other in the following situations:
+
+   - Controllers use scopes to expose controller methods to templates (see {@link
+     api/ng.directive:ngController ng-controller}).
+
+   - Controllers define methods (behavior) that can mutate the model (properties on the scope).
+
+   - Controllers may register {@link api/ng.$rootScope.Scope#$watch watches} on
+     the model. These watches execute immediately after the controller behavior executes.
+
+See the {@link api/ng.directive:ngController ng-controller} for more
+information.
+
+
+### Scope `$watch` Performance Considerations
+
+Dirty checking the scope for property changes is a common operation in Angular and for this reason
+the dirty checking function must be efficient. Care should be taken that the dirty checking
+function does not do any DOM access, as DOM access is orders of magnitude slower then property
+access on JavaScript object.
+
@@ -13,19 +13,19 @@
 <a name="H1_1"></a>
 # License

-`Angular` is an open source project licensed under the {@link
+AngularJS is an open source project licensed under the {@link
 http://github.com/angular/angular.js/blob/master/LICENSE MIT license}. Your contributions are
-always welcome. When working with `angular` source base, please follow the guidelines provided on
+always welcome. When working with AngularJS code base, please follow the guidelines provided on
 this page.


 <a name="H1_2"></a>
 # Contributing to Source Code

-We'd love for you to contribute to our source code and to make `angular` even better than it is
-today! Here are the guidelines we'd like you to use:
+We'd love for you to contribute to our source code and to make AngularJS even better than it is
+today! Here are the guidelines we'd like you to follow:

-* Major changes that you intend to contribute to the project must be discussed first on our {@link
+* Major changes that you intend to contribute to the project should be discussed first on our {@link
 https://groups.google.com/forum/?hl=en#!forum/angular mailing list} so that we can better
 coordinate our efforts, prevent  duplication of work, and help you to craft the change so that it
 is successfully accepted upstream.
@@ -64,46 +64,44 @@ inheritance only when absolutely necessary.
 external API. See our existing code to see what we mean.

  * We don't go crazy with type annotations for private internal APIs unless it's an internal API
-that is used throughout `angular`. The best guidance is to do what makes the most sense.
+that is used throughout AngularJS. The best guidance is to do what makes the most sense.


 <a name="H1_4"></a>
 # Checking Out and Building Angular

-The `angular` source code is hosted at {@link http://github.com Github}, which we also use to
-accept code contributions. Several steps are needed to check out and build `angular`:
+The AngularJS source code is hosted at {@link http://github.com Github}, which we also use to
+accept code contributions. The AngularJS repository can be found at **<https://github.com/angular/angular.js>**.
+
+Several steps are needed to check out and build AngularJS:


 ## Installation Dependencies

-Before you can build `angular`, you must install or configure the following dependencies on your
+Before you can build AngularJS, you must install or configure the following dependencies on your
 machine:

-* {@link http://rake.rubyforge.org Rake}: We use Rake as our build system, which is pre-installed
-on most Macintosh and Linux machines. If that is not true in your case, you can grab it from the
-Rake website.
-
-* {@link http://nodejs.org Node.js}: We use Node to generate the documentation and to run a
-development web server. Depending on your system, you can install Node either from source or as a
-pre-packaged bundle.
-
-  You'll also need npm and the following npm modules:
-
-  * install npm: `curl http://npmjs.org/install.sh | sh`
-  * install q: `npm install q`
-  * install qq: `npm install qq`
-  * install q-fs: `npm install q-fs`
-  * install jasmine-node: `npm install jasmine`
-
-
-
-* Java: The Java runtime is used to run {@link http://code.google.com/p/js-test-driver
-JsTestDriver} (JSTD), which we use to run our unit test suite. JSTD binaries are part of the
-`angular` source base, which means there is no need to install or configure it separately.
-
 * Git: The {@link http://help.github.com/mac-git-installation Github Guide to Installing Git} is
 quite a good source for information on Git.

+* {@link http://nodejs.org Node.js}: We use Node to generate the documentation, run a
+development web server, run tests, and generate a build. Depending on your system, you can install Node either from source or as a
+pre-packaged bundle.
+
+* {@link http://www.java.com Java}: JavaScript is minified using
+{@link https://developers.google.com/closure/ Closure Tools} jar. Make sure you have Java (version 6 or higher) installed
+and included in your {@link http://docs.oracle.com/javase/tutorial/essential/environment/paths.html PATH} variable.
+
+  Once installed, you'll also need several npms (node packages), which you can install once you checked out a local copy
+  of the Angular repository (see below) with:
+
+  * `cd angular.js`
+  * `npm install`
+
+* {@link http://gruntjs.com Grunt}: We use Grunt as our build system. Install the grunt command-line tool globally with:
+
+  * `sudo npm install -g grunt-cli`
+

 ## Creating a Github Account and Forking Angular

@@ -112,31 +110,39 @@ Afterwards, go ahead and {@link http://help.github.com/forking fork} the {@link
 https://github.com/angular/angular.js main angular repository}.


-## Building `Angular`
+## Building AngularJS

-To build `angular`, you check out the source code and use Rake to generate the non-minified and
-minified `angular` files:
+To build AngularJS, you check out the source code and use Grunt to generate the non-minified and
+minified AngularJS files:

 1. To clone your Github repository, run:

        git clone git@github.com:<github username>/angular.js.git

-2. To go to the `angular` directory, run:
+2. To go to the AngularJS directory, run:

        cd angular.js

-3. To add the main `angular` repository as an upstream remote to your repository, run:
+3. To add the main AngularJS repository as an upstream remote to your repository, run:

        git remote add upstream https://github.com/angular/angular.js.git

-4. To build `angular`, run:
+4. To add node.js dependencies
+
+        npm install
+
+5. To build AngularJS, run:
+
+        grunt package
+
+NOTE: If you're using Windows you must run your command line with administrative privileges (right click, run as
+Administrator).

-        rake package

 The build output can be located under the `build` directory. It consists of the following files and
 directories:

-* `angular-<version>.tgz` — This is the complete tarball, which  contains all of the release build
+* `angular-<version>.zip` — This is the complete zip file, which  contains all of the release build
 artifacts.

 * `angular.js` — The non-minified `angular` script.
@@ -145,8 +151,6 @@ artifacts.

 * `angular-scenario.js` — The `angular` End2End test runner.

-* `angular-ie-compat.js` —  The Internet Explorer compatibility patch file.
-
 * `docs/` — A directory that contains all of the files needed to run `docs.angularjs.org`.

 * `docs/index.html` — The main page for the documentation.
@@ -154,60 +158,78 @@ artifacts.
 * `docs/docs-scenario.html` — The End2End test runner for the documentation application.


+<a name="webserver"></a>
 ## Running a Local Development Web Server

-To debug or test code, it is often useful to have a local HTTP server. For this purpose, we have
+To debug code and run end-to-end tests, it is often useful to have a local HTTP server. For this purpose, we have
 made available a local web server based on Node.js.

 1. To start the web server, run:

-        ./nodeserver.sh
+        grunt webserver

 2. To access the local server, go to this website:

        http://localhost:8000/

-   By default, it serves the contents of the `angular` project directory.
+   By default, it serves the contents of the AngularJS project directory.


 <a name="unit-tests"></a>
 ## Running the Unit Test Suite

-Our unit and integration tests are written with Jasmine and executed with JsTestDriver.  To run the
-tests:
+Our unit and integration tests are written with Jasmine and executed with Karma.  To run all of the
+tests once on Chrome run:

-1. To start the JSTD server, run:
+    grunt test:unit

-        ./server.sh
+To run the tests on other browsers (Chrome, ChromeCanary, Firefox, Opera and Safari are pre-configured) use:

-2. To capture one or more browsers, go to this website:
+    grunt test:unit --browsers Opera,Firefox
+
+Note there should be _no spaces between browsers_. `Opera, Firefox` is INVALID.
+
+During development it's however more productive to continuously run unit tests every time the source or test files
+change. To execute tests in this mode run:
+
+1. To start the Karma server, capture Chrome browser and run unit tests, run:
+
+        grunt autotest:jqlite
+
+2. To capture more browsers, open this url in the desired browser (url might be different if you have multiple instance
+   of Karma running, read Karma's console output for the correct url):

        http://localhost:9876/

-3. To trigger a test execution, run:
-
-        ./test.sh
-
-4. To automatically run the test suite each time one or more of the files in the project directory
-is changed, you can install `watchr` and then run:
-
-        watchr watchr.rb
-
-5. To view the output of each test run, you can tail this log file:
-
-        ./logs/jstd.log
+3. To re-run tests just change any source or test file.


-## Running the End2End Test Suite
+To learn more about all of the preconfigured Grunt tasks run:

-To run the End2End test suite:
+    grunt --help
+
+
+## Running the end-to-end Test Suite
+
+To run the E2E test suite:
+
+1. Start the local web server if it's not running already.
+
+        grunt webserver

-1. Start the local web server.
 2. In a browser, go to:

        http://localhost:8000/build/docs/docs-scenario.html

-   The tests are executed automatically.
+   or in terminal run:
+
+        grunt test:end2end
+
+For convenience you can also simply run:
+
+        grunt test:e2e
+
+This will start the webserver for you and run the tests.



@@ -216,31 +238,36 @@ To run the End2End test suite:

 To create and submit a change:

-1. Create a new branch off the master for your changes:
+1. <a name="CLA"></a>
+   Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code changes to be
+   accepted, the CLA must be signed. It's a quick process, we promise!

-        git branch my-fix-branch
+   For individuals we have a [simple click-through form](http://code.google.com/legal/individual-cla-v1.0.html). For
+   corporations we'll need you to
+   [print, sign and one of scan+email, fax or mail the form](http://code.google.com/legal/corporate-cla-v1.0.html).

-2. Check out the branch:

-        git checkout my-fix-branch
+2. Create and checkout a new branch off the master branch for your changes:
+
+        git checkout -b my-fix-branch master

 3. Create your patch, make sure to have plenty of tests (that pass).

-4. Commit your changes:
+4. Commit your changes and create a descriptive commit message (the commit message is used to generate release notes,
+   please check out our
+   [commit message conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#)
+   and our commit message presubmit hook `validate-commit-msg.js`):

        git commit -a

-5. Run JavaScript Lint and be sure to address all new warnings and errors:
-
-        rake lint
-
-6. Push your branch to Github:
+5. Push your branch to Github:

        git push origin my-fix-branch

-7. In Github, send a pull request to `angular:master`.
+6. In Github, send a pull request to `angular:master`.

-8. When the patch is reviewed and merged, delete your branch and pull yours — and other — changes
+
+7. When the patch is reviewed and merged, delete your branch and pull yours — and other — changes
 from the main (upstream) repository:

  1. To delete the branch in Github, run:
@@ -2,10 +2,9 @@
@name Downloading
@description

-# Including angular scripts from the angular server
-The quickest way to get started is to point your html `<script>` tag to a
-<http://code.angularjs.org/> URL.  This way, you don't have to download anything or maintain a
-local copy.
+# Including angular scripts from the Google CDN
+The quickest way to get started is to point your html `<script>` tag to a Google CDN URL.
+This way, you don't have to download anything or maintain a local copy.

 There are two types of angular script URLs you can point to, one for development and one for
 production:
@@ -15,21 +14,25 @@ development.
 * __angular-<version>.min.js__ — This is the minified version, which we strongly suggest you use in
 production.

-To point your code to an angular script on the angular server, use the following template.  This
-example points to (non-minified) version 0.10.6:
+To point your code to an angular script on the Google CDN server, use the following template.  This
+example points to the minified version 1.0.2:

 <pre>
  <!doctype html>
  <html ng-app>
    <head>
      <title>My Angular App</title>
-      <script src="http://code.angularjs.org/angular-0.10.6.js"></script>
+      <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.0.2/angular.min.js"></script>
    </head>
    <body>
    </body>
  </html>
 </pre>

+Note that only versions 1.0.1 and above are available on the CDN, if you need an earlier version
+you can use the <http://code.angularjs.org/> URL which was the previous recommended location for
+hosted code source. If you're still using the angular server you should switch to the CDN version
+for even faster loading times.

 # Downloading and hosting angular files locally
 This option is for those who want to work with angular offline, or those who want to host the
@@ -42,29 +45,31 @@ Download the version you want and have fun.

 Each directory under <http://code.angularjs.org/> includes the following set of files:

-* __`angular-<version>.js`__ — This file is non-obfuscated, non-minified, and human-readable by
+* __`angular.js`__ — This file is non-obfuscated, non-minified, and human-readable by
 opening it it any editor or browser. In order to get better error messages during development, you
 should always use this non-minified angular script.

-* __`angular-<version>.min.js`__ — This is a minified and obfuscated version of
-`angular-<version>.js` created with the Closure compiler. Use this version for production in order
+* __`angular.min.js`__ — This is a minified and obfuscated version of
+`angular.js` created with the Closure compiler. Use this version for production in order
 to minimize the size of the application that is downloaded by your user's browser.

-* __`angular-<version>.tgz`__ — This is a tarball archive that contains all of the files released
+* __`angular.zip`__ — This is a zip archive that contains all of the files released
 for this angular version. Use this file to get everything in a single download.

-* __`angular-ie-compat-<version>.js`__ — This is a special file that contains code and data
-specifically tailored for getting Internet Explorer to work with angular. If you host your own copy
-of angular files, make sure that this file is available for download, and that it resides under the
-same parent path as `angular-<version>.js` or `angular-<version>.min.js`.
-
-* __`angular-mocks-<version>.js`__ — This file contains an implementation of mocks that makes
+* __`angular-mocks.js`__ — This file contains an implementation of mocks that makes
 testing angular apps even easier. Your unit/integration test harness should load this file after
 `angular-<version>.js` is loaded.

-* __`angular-scenario-<version>.js`__ — This file is a very nifty JavaScript file that allows you
+* __`angular-scenario.js`__ — This file is a very nifty JavaScript file that allows you
 to write and execute end-to-end tests for angular applications.

-* __`docs-<version>`__ — this directory contains all the files that compose the
+* __`angular-loader.min.js`__ — Module loader for Angular modules. If you are loading multiple script files containing
+ Angular modules, you can load them asynchronosuly and in any order as long as you load this file first. Often the
+ contents of this file are copy&pasted into the `index.html` to avoid even the inial request to `angular-loader.min.js`.
+ See [angular-seed](https://github.com/angular/angular-seed/blob/master/app/index-async.html) for an example of usage.
+
+* __`angular-resource.js`__, __`angular-cookies.js`__, etc - extra Angular modules with additional functionality.
+
+* __`docs`__ — this directory contains all the files that compose the
 <http://docs.angularjs.org/> documentation app. These files are handy to see the older version of
 our docs, or even more importantly, view the docs offline.
@@ -4,78 +4,213 @@

 #FAQ

-### Why is this project called "angular"? Why is the namespace called "ng"?
+## Questions

-Because HTML has angular brackets and "ng" sounds like "angular".
+### Why is this project called "AngularJS"? Why is the namespace called "ng"?

-### Is <angular/> an HTML5 tag?
+Because HTML has Angular brackets and "ng" sounds like "Angular".

-No, <angular/> is not an HTML5 tag. angular is an orthogonal project to HTML5; you can use the two
-together.

-### Is angular a {library, framework, DOM manipulation library, widget library, native plugin}?
+### Is AngularJS a library, framework, plugin or a browser extension?

-No, angular is none of these. You don't call its functions, it does not call your functions,
-it does not provide a way to manipulate DOM, but does provide primitives to create UI projections
-of your data. There are lots of existing widget libraries which you can integrate with angular.
-It is 100% JavaScript, 100% client side and compatible with both desktop and mobile browsers.
+AngularJS fits the definition of a framework the best, even though it's much more lightweight than
+a typical framework and that's why many confuse it with a library.

-### Do I need to worry about security holes in angular?
+AngularJS is 100% JavaScript, 100% client side and compatible with both desktop and mobile browsers.
+So it's definitely not a plugin or some other native browser extension.

-Like with any technology, angular is not impervious to attack. angular does, however, provide
-built-in protection from basic security holes including cross-site scripting and HTML injection
-attacks. angular does round-trip escaping on all strings for you.

-### Can I download the source, build, and host the angular environment locally?
+### Is AngularJS a templating system?

-Yes. See instructions in {@link downloading}.
-
-### Is angular a templating system?
-
-At the highest level, angular does look like a just another templating system. But there is one
-important reason why angular templating system is different and makes it very good fit for
-application development: bidirectional data binding. The template is compiled on the browser and
-the compilation step produces a live view. This means you, the developer, don't need to write
+At the highest level, Angular does look like a just another templating system. But there is one
+important reason why the Angular templating system is different, that makes it very good fit for
+application development: bidirectional data binding. The template is compiled in the browser and
+the compilation step produces a live view. This means you, the developers, don't need to write
 code to constantly sync the view with the model and the model with the view as in other
 templating systems.

-### What browsers does angular work with?

-Webkit-based browsers (Safari, Chrome, iPhone, Android, WebOS, BlackBerry 6), Firefox, IE6 and
-above. Note that CSS only works on IE7 and above.
+### Do I need to worry about security holes in AngularJS?

-### What's angular's performance like?
+Like any other technology, AngularJS is not impervious to attack. Angular does, however, provide
+built-in protection from basic security holes including cross-site scripting and HTML injection
+attacks. AngularJS does round-trip escaping on all strings for you and even offers XSRF protection
+for server-side communication.

-angular takes ~300ms to load, render, and compile. In Chrome it uses about 2-5MB of memory. Your
-app's performance will vary depending on how many bindings you use.
+AngularJS was designed to be compatible with other security measures like Content Security Policy
+(CSP), HTTPS (SSL/TLS) and server-side authentication and authorization that greatly reduce the
+possible attack vectors and we highly recommended their use.

-### How big is the angular bootstrap JS file that I need to include?

-The size of the library itself is < 50KB compressed and obfuscated.
+### Can I download the source, build, and host the AngularJS environment locally?

-### Can I use the open-source Closure Library with angular?
+Yes. See instructions in {@link downloading}.
+
+
+
+### What browsers does Angular work with?
+
+We run our extensive test suite against the following browsers: Safari, Chrome, Firefox, Opera,
+IE8, IE9 and mobile browsers (Android, Chrome Mobile, iOS Safari). See {@link guide/ie Internet
+Explorer Compatibility} for more details in supporting legacy IE browsers.
+
+
+### What's Angular's performance like?
+
+The startup time heavily depends on your network connection, state of the cache, browser used and
+available hardware, but typically we measure bootstrap time in tens or hundreds of milliseconds.
+
+The runtime performance will vary depending on the number and complexity of bindings on the page
+as well as the speed of your backend (for apps that fetch data from the backend). Just for an
+illustration we typically build snappy apps with hundreds or thousands of active bindings.
+
+
+### How big is the angular.js file that I need to include?
+
+The size of the file is < 29KB compressed and minified.
+
+
+### Can I use the open-source Closure Library with Angular?

 Yes, you can use widgets from the {@link http://code.google.com/closure/library Closure Library}
-in angular.
+in Angular.

-### Does angular use the jQuery library?
+### Does Angular use the jQuery library?

-Yes, angular uses {@link http://jquery.com/ jQuery}, the open source DOM manipulation library.
-If jQuery is not present in your script path, angular falls back on its own implementation of
-{@link api/angular.element jQuery lite}. If jQuery is present in the path, angular uses it to
-manipulate the DOM.
+Yes, Angular can use {@link http://jquery.com/ jQuery} if it's present in your app when the
+application is being bootstrapped. If jQuery is not present in your script path, Angular falls back
+to its own implementation of the subset of jQuery that we call {@link api/angular.element  jQLite}.

-### What is testability like in angular?

-Very testable. It has an integrated dependency injection framework. See
-{@link api/angular.module.ng service} for details.
+### What is testability like in Angular?

-### How can I learn more about angular?
+Very testable and designed this way from ground up. It has an integrated dependency injection
+framework, provides mocks for many heavy dependencies (server-side communication). See
+{@link api/ng service} for details.

-Watch the July 28, 2010 talk
-"{@link http://www.youtube.com/watch?v=elvcgVSynRg| Angular: A Radically Different Way of Building
-AJAX Apps}".

-### How is angular licensed?
+### How can I learn more about Angular?
+
+Watch the July 17, 2012 talk
+"{@link http://www.youtube.com/watch?v=1CpiB3Wk25U AngularJS Intro + Dependency Injection}".
+
+
+### How is Angular licensed?

 The MIT License.
+
+### Can I download and use the Angular logo artwork?
+
+Yes! You can find design files in our github repository, under "{@link https://github.com/angular/angular.js/tree/master/images/logo
+angular.js/images/logo}"
+The logo design is licensed under a "{@link http://creativecommons.org/licenses/by-sa/3.0/
+Creative Commons Attribution-ShareAlike 3.0 Unported License}". If you have some other use in mind, contact us.
+
+### How can I get some AngularJS schwag?
+
+We often bring a few t-shirts and stickers to events where we're presenting. If you want to order your own, the folks who
+make our schwag will be happy to do a custom run for you, based on our existing template. By using the design they have on file,
+they'll waive the setup costs, and you can order any quantity you need.
+
+**Stickers**
+Contact Tom Witting (or anyone in sales) via email at tom@stickergiant.com, and tell him you want to order some AngularJS
+stickers just like the ones in job #42711. You'll have to give them your own info for billing and shipping.
+
+As long as the design stays exactly the same, {@link http://www.stickergiant.com StickerGiant} will give you a reorder discount.
+
+
+## Common Pitfalls
+
+The Angular support channel (#angularjs on Freenode) sees a number of recurring pitfalls that new users of Angular fall into.
+This document aims to point them out before you discover them the hard way.
+
+### DOM Manipulation
+
+Stop trying to use jQuery to modify the DOM in controllers. Really.
+That includes adding elements, removing elements, retrieving their contents, showing and hiding them.
+Use built-in directives, or write your own where necessary, to do your DOM manipulation.
+See below about duplicating functionality.
+
+If you're struggling to break the habit, consider removing jQuery from your app.
+Really. Angular has the $http service and powerful directives that make it almost always unnecessary.
+Angular's bundled jQLite has a handful of the features most commonly used in writing Angular directives, especially binding to events.
+
+### Trying to duplicate functionality that already exists
+
+There's a good chance that your app isn't the first to require certain functionality.
+There are a few pieces of Angular that are particularly likely to be reimplemented out of old habits.
+
+**ng-repeat**
+
+`ng-repeat` gets this a lot.
+People try to use jQuery (see above) to add more elements to some container as they're fetched from the server.
+No, bad dog.
+This is what `ng-repeat` is for, and it does its job very well.
+Store the data from the server in an array on your `$scope`, and bind it to the DOM with `ng-repeat`.
+
+**ng-show**
+
+`ng-show` gets this frequently too.
+Conditionally showing and hiding things using jQuery is a common pattern in other apps, but Angular has a better way.
+`ng-show` (and `ng-hide`) conditionally show and hide elements based on boolean expressions.
+Describe the conditions for showing and hiding an element in terms of `$scope` variables:
+
+    <div ng-show="!loggedIn">Click <a href="#/login">here</a> to log in</div>
+
+Note also the counterpart `ng-hide` and similar `ng-disabled`.
+Note especially the powerful `ng-switch` that should be used instead of several mutually exclusive `ng-show`s.
+
+**ng-class**
+
+`ng-class` is the last of the big three.
+Conditionally applying classes to elements is another thing commonly done manually using jQuery.
+Angular, of course, has a better way.
+You can give `ng-class` a whitespace-separated set of class names, and then it's identical to ordinary `class`.
+That's not very exciting, so there's a second syntax:
+
+    <div ng-class="{ errorClass: isError, warningClass: isWarning, okClass: !isError && !isWarning }">...</div>
+
+Where you give `ng-class` an object, whose keys are CSS class names and whose values are conditional expressions using `$scope` variables.
+The element will then have all the classes whose conditions are truthy, and none of those whose conditions are falsy.
+
+Note also the handy `ng-class-even` and `ng-class-odd`, and the related though somewhat different `ng-style`.
+
+
+### `$watch` and `$apply`
+
+Angular's two-way data binding is the root of all awesome in Angular.
+However, it's not magic, and there are some situations where you need to give it a nudge in the right direction.
+
+When you bind a value to an element in Angular using `ng-model`, `ng-repeat`, etc., Angular creates a `$watch` on that value.
+Then whenever a value on a scope changes, all `$watch`es observing that element are executed, and everything updates.
+
+Sometimes, usually when you're writing a custom directive, you will have to define your own `$watch` on a scope value to make the directive react to changes.
+
+On the flip side, sometimes you change a scope value in some code but the app doesn't react to it.
+Angular checks for scope variable changes after pieces of your code have finished running; for example, when `ng-click` calls a function on your scope, Angular will check for changes and react.
+However, some code is outside of Angular and you'll have to call `scope.$apply()` yourself to trigger the update.
+This is most commonly seen in event handlers in custom directives.
+
+### Combining `ng-repeat` with other directives
+
+`ng-repeat` is extremely useful, one of the most powerful directives in Angular.
+However the transformation it applies to the DOM is substantial.
+Therefore applying other directives (such as `ng-show`, `ng-controller` and others) to the same element as `ng-repeat` generally leads to problems.
+
+If you want to apply a directive to the whole repeat, wrap the repeat in a parent element and put it there.
+If you want to apply a directive to each inner piece of the repeat, put it on a child of the element with `ng-repeat`.
+
+### `$rootScope` exists, but it can be used for evil
+
+Scopes in Angular form a hierarchy, prototypically inheriting from a root scope at the top of the tree.
+Usually this can be ignored, since most views have a controller, and therefore a scope, of their own.
+
+Occasionally there are pieces of data that you want to make global to the whole app.
+For these, you can inject `$rootScope` and set values on it like any other scope.
+Since the scopes inherit from the root scope, these values will be available to the expressions attached to directives like `ng-show` just like values on your local `$scope`.
+
+Of course, global state sucks and you should use `$rootScope` sparingly, like you would (hopefully) use with global variables in any language.
+In particular, don't use it for code, only data.
+If you're tempted to put a function on `$rootScope`, it's almost always better to put it in a service that can be injected where it's needed, and more easily tested.
+
+Conversely, don't create a service whose only purpose in life is to store and return bits of data.
@@ -2,142 +2,38 @@
@name Getting Started
@description

-# Hello World!
+We want you to have an easy time while starting to use Angular.  We've put together the following steps on your path to
+becoming an Angular expert.

-A great way for you to get started with AngularJS is to create the tradtional
-"Hello World!" app:
-
-1. In your favorite text editor, create an HTML file
-   (for example, `helloworld.html`).
-2. From the __Source__ box below, copy and paste the code into your HTML file.
-   (Double-click on the source to easily select all.)
-3. Open the file in your web browser.
-
-<doc:example>
-    <doc:source>
-        Hello {{'World'}}!
-    </doc:source>
-</doc:example>
-
-The resulting web page should look something like the following:
-
-<img class="center" src="img/helloworld.png" border="1">
-
-Now let's take a closer look at that code, and see what is going on behind
-the scenes.
-
-The `ng-app` tags tells angular to process the entire HTML page and bootstrap the app when the page
-is loaded:
-
-<pre>
-    <html ng-app>
-</pre>
-
-The next line downloads the angular script:
-
-<pre>
-    <script src="http://code.angularjs.org/angular-?.?.?.min.js"></script>
-</pre>
-
-(For details on what happens when angular processes an HTML page,
-see {@link guide/dev_guide.bootstrap Bootstrap}.)
-
-Finally, this line in the `<body>` of the page is the template that describes
-how to display our greeting in the UI:
-
-<pre>
-    Hello {{'World'}}!
-</pre>
-
-Note the use of the double curly brace markup (`{{ }}`) to bind the expression to
-the greeting text. Here the expression is the string literal 'World'.
-
-Next let's look at a more interesting example, that uses AngularJS to
-bind a dynamic expression to our greeting text.
-
-# Hello AngularJS World!
-
-This example demonstrates angular's two-way data binding:
-
-1. Edit the HTML file you created in the "Hello World!" example above.
-2. Replace the contents of `<body>` with the code from the __Source__ box below.
-3. Refresh your browser window.
-
-<doc:example>
- <doc:source>
-  Your name: <input type="text" ng-model="yourname" value="World"/>
-  <hr/>
-  Hello {{yourname}}!
- </doc:source>
-</doc:example>
-
-After the refresh, the page should look something like this:
-
-<img class="left" src="img/helloworld_2way.png" border="1" />
-
-These are some of the important points to note from this example:
-
-* The text input {@link api/angular.module.ng.$compileProvider.directive directive}
-  is bound to a model variable called `yourname`.
-* The double curly braces notation binds the `yourname` model to the greeting text.
-
-* You did not need to explicitly register an event listener or define an event handler for events!
-
-Now try typing your name into the input box, and notice the immediate change to
-the displayed greeting. This demonstrates the concept of angular's
-{@link guide/dev_guide.templates.databinding bi-directional data binding}. Any changes to the input
-field are immediately
-reflected in the model (one direction), and any changes to the model are
-reflected in the greeting text (the other direction).
+1. Read the {@link guide/concepts conceptual overview}.<br/>Understand Angular's vocabulary and how all the Angular
+   components work together.
+1. Do the {@link tutorial/ AngularJS Tutorial}.<br/>Walk end-to-end through building and application complete with tests
+   on top of a node.js web server.  Covers every major AngularJS feature and show you how to set up your development
+   environment.
+1. Download or clone the {@link https://github.com/angular/angular-seed Seed App project template}.<br/>Gives you a
+   starter app with a directory layout, test harness, and scripts to begin building your application.


-# Anatomy Of An Angular App
+#Further Steps

-This section describes the 3 parts of an angular app, and explains how they map to the
-Model-View-Controller design pattern:
+##Watch Videos

-## Templates
+If you haven’t had a chance to watch the videos from the homepage, please check out:

-Templates, which you write in HTML and CSS, serve as the View. You add elements, attributes, and
-markup to HTML, which serve as instructions to the angular compiler. The angular compiler is fully
-extensible, meaning that with angular you can build your own declarative language on top of HTML!
+* {@link http://www.youtube.com/watch?v=WuiHuZq_cg4&list=PL173F1A311439C05D&context=C48ac877ADvjVQa1PpcFONnl4Q5x8hqvT6tRBTE-m0-Ym47jO3PEE%3D Introduction to AngularJS}
+* {@link http://www.youtube.com/watch?v=Yg-R1gchccg&list=PL173F1A311439C05D&context=C48ac877ADvjVQa1PpcFONnl4Q5x8hqvT6tRBTE-m0-Ym47jO3PEE%3D Creating Directives}
+* {@link http://www.youtube.com/watch?v=IRelx4-ISbs&list=PL173F1A311439C05D&context=C48ac877ADvjVQa1PpcFONnl4Q5x8hqvT6tRBTE-m0-Ym47jO3PEE%3D Communicating with Servers}

+And visit our {@link http://www.youtube.com/user/angularjs YouTube channel} for more AngularJS video presentations and
+tutorials.

-## Application Logic and Behavior
+##Subscribe

-Application Logic and Behavior, which you define in JavaScript, serve as the Controller. With
-angular (unlike with standard AJAX applications) you don't need to write additional listeners or
-DOM manipulators, because they are built-in. This feature makes your application logic very easy to
-write, test, maintain, and understand.
+* Subscribe to the {@link http://groups.google.com/forum/?fromgroups#!forum/angular mailing list}.  Ask questions here!
+* Follow us on {@link https://twitter.com/intent/follow?original_referer=http%3A%2F%2Fangularjs.org%2F&region=follow_link&screen_name=angularjs&source=followbutton&variant=2.0 Twitter}
+* Add us to your circles on {@link https://plus.google.com/110323587230527980117/posts Google+}

+##Read more

-## Data
-
-The Model is referenced from properties on {@link guide/dev_guide.scopes angular scope objects}.
-The data in your model could be Javascript objects, arrays, or primitives, it doesn't matter.  What
-matters is that these are all referenced by the scope object.
-
-Angular employs scopes to keep your data model and your UI in sync.  Whenever something occurs to
-change the state of the model, angular immediately reflects that change in the UI, and vice versa.
-
-The following illustration shows the parts of an angular application and how they work together:
-
-<img class="left" src="img/angular_parts.png" border="0" />
-
-In addition, angular comes with a set of Services, which have the following properties:
-
-* The services provided are very useful for building web applications.
-* You can extend and add application-specific behavior to services.
-* Services include Dependency-Injection, XHR, caching, URL routing, and browser abstraction.
-
-
-# Where To Go Next
-
-* If you like what you've learned so far, you should definitely check out our awesome {@link
-tutorial/ Tutorial}, which walks you through the process of building real apps with AngularJS.
-
-* For further explanations and examples of the AngularJS concepts presented on this page, see the
-{@link guide/index Developer Guide}.
-
-* For additional hands-on examples of using AngularJS, including more source  code that you can
-copy and paste into your own pages, take a look through the {@link cookbook/ Cookbook}.
+The AngularJS documentation includes the {@link guide/index Developer Guide} covering concepts and the
+{@link api/ API Reference} for syntax and usage.
@@ -0,0 +1,115 @@
+@ngdoc overview
+@name Tutorial: Index
+@description
+
+A great way to get introduced to AngularJS is to work through this tutorial, which walks you through
+the construction of an AngularJS web app. The app you will build is a catalog that displays a list
+of Android devices, lets you filter the list to see only devices that interest you, and then view
+details for any device.
+
+<img class="diagram" src="img/tutorial/catalog_screen.png" width="488" height="413">
+
+Work through the tutorial to see how Angular makes browsers smarter — without the use of extensions
+or plug-ins. As you work through the tutorial, you will:
+
+* See examples of how to use client-side data binding and dependency injection to build dynamic
+views of data that change immediately in response to user actions.
+* See how Angular creates listeners on your data without the need for DOM manipulation.
+* Learn a better, easier way to test your web apps.
+* Learn how to use Angular services to make common web tasks, such as getting data into your app,
+easier.
+
+And all of this works in any browser without modification to the browser!
+
+When you finish the tutorial you will be able to:
+
+* Create a dynamic application that works in any browser.
+* Define the differences between Angular and common JavaScript frameworks.
+* Understand how data binding works in AngularJS.
+* Use the angular-seed project to quickly boot-strap your own projects.
+* Create and run tests.
+* Identify resources for learning more about AngularJS.
+
+The tutorial guides you through the entire process of building a simple application, including
+writing and running unit and end-to-end tests. Experiments at the end of each step provide
+suggestions for you to learn more about AngularJS and the application you are building.
+
+You can go through the whole tutorial in a couple of hours or you may want to spend a pleasant day
+really digging into it. If you're looking for a shorter introduction to AngularJS, check out the
+{@link misc/started Getting Started} document.
+
+
+
+
+
+
+
+# Working with the code
+
+You can follow this tutorial and hack on the code in either the Mac/Linux or the Windows
+environment. The tutorial relies on the use of Git versioning system for source code management.
+You don't need to know anything about Git to follow the tutorial. Select one of the tabs below
+and follow the instructions for setting up your computer.
+
+<div class="tabbable" show="true">
+  <div class="tab-pane well" id="git-mac" title="Git on Mac/Linux">
+    <ol>
+      <li><p>You will need Node.js and Karma to run unit tests, so please verify that you have
+      <a href="http://nodejs.org/">Node.js</a> v0.8 or better installed
+      and that the <code>node</code> executable is on your <code>PATH</code> by running the following
+      command in a terminal window:</p>
+      <pre>node --version</pre>
+      <p>Additionally install <a href="http://karma-runner.github.io/">Karma</a> if you
+      don't have it already:</p>
+      <pre>npm install -g karma</pre>
+      <li><p>You'll also need Git, which you can get from
+         <a href="http://git-scm.com/download">the Git site</a>.</p></li>
+      <li><p>Clone the angular-phonecat repository located at
+      <a href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
+      <pre>git clone git://github.com/angular/angular-phonecat.git</pre>
+      <p>This command creates the <code>angular-phonecat</code> directory in your current
+directory.</p></li>
+      <li><p>Change your current directory to <code>angular-phonecat</code>:</p>
+      <pre>cd angular-phonecat</pre>
+      <p>The tutorial instructions assume you are running all commands from the <code>angular-phonecat</code>
+directory.</p></li>
+      <li><p>You will need an http server running on your system. Mac and Linux machines typically
+have Apache pre-installed, but If you don't already have one installed, you can use <code>node</code>
+to run <code>scripts/web-server.js</code>,  a simple bundled http server.</p></li>
+    </ol>
+  </div>
+
+  <div class="tab-pane well" id="git-win" title="Git on Windows">
+    <ol>
+      <li><p>You will need Node.js and Karma to run unit tests, so please verify that you have
+        <a href="http://nodejs.org/">Node.js</a> v0.8 or better installed
+        and that the <code>node</code> executable is on your <code>PATH</code> by running the following
+        command in a terminal window:</p>
+        <pre>node --version</pre>
+        <p>Additionally install <a href="http://karma-runner.github.io/">Karma</a> if you
+           don't have it already:</p>
+        <pre>npm install -g karma</pre>
+      </li>
+      <li><p>You'll also need Git, which you can get from
+               <a href="http://git-scm.com/download">the Git site</a>.</p></li>
+      <li><p>Clone the angular-phonecat repository located at <a
+      href="https://github.com/angular/angular-phonecat">Github</a> by running the following command:</p>
+      <pre>git clone git://github.com/angular/angular-phonecat.git</pre>
+      <p>This command creates the <code>angular-phonecat</code> directory in your current directory.</p></li>
+      <li><p>Change your current directory to <code>angular-phonecat</code>:</p>
+      <pre>cd angular-phonecat</pre>
+      <p>The tutorial instructions assume you are running all commands from the <code>angular-phonecat</code>
+directory.</p>
+      <p>You should run all <code>git</code> commands from Git bash.</p>
+      <p>Other commands like <code>test.bat</code> or <code>e2e-test.bat</code> should be
+executed from the Windows command line.</li>
+      <li><p>You need an http server running on your system, but if you don't already have one
+already installed, you can use <code>node</code> to run <code>scripts\web-server.js</code>, a simple
+bundled http server.</p></li>
+    </ol>
+  </div>
+
+The last thing to do is to make sure your computer has a web browser and a good text editor
+installed. Now, let's get some cool stuff done!
+
+{@link step_00 <span class="btn btn-primary">Get Started!</span>}
@@ -0,0 +1,212 @@
+@ngdoc overview
+@name Tutorial: 0 - Bootstrapping
+@description
+
+<ul doc-tutorial-nav="0"></ul>
+
+
+You are now ready to build the AngularJS phonecat app. In this step, you will become familiar
+with the most important source code files, learn how to start the development servers bundled with
+angular-seed, and run the application in the browser.
+
+
+<div class="tabbable" show="true" ng-model="$cookies.platformPreference">
+  <div class="tab-pane well" id="git-mac" title="Git on Mac/Linux" value="gitUnix">
+    <ol>
+      <li><p>In <code>angular-phonecat</code> directory, run this command:</p>
+      <pre>git checkout -f step-0</pre>
+      <p>This resets your workspace to step 0 of the tutorial app.</p>
+      <p>You must repeat this for every future step in the tutorial and change the number to
+      the number of the step you are on. This will cause any changes you made within
+      your working directory to be lost.</p></li>
+
+      <li>To see the app running in a browser, do one of the following:
+        <ul>
+          <li><b>For node.js users:</b>
+            <ol>
+              <li>In a <i>separate</i> terminal tab or window, run
+<code>node ./scripts/web-server.js</code> to start the web server.</li>
+              <li>Open a browser window for the app and navigate to <a
+href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html</a></li>
+            </ol>
+          </li>
+          <li><b>For other http servers:</b>
+            <ol>
+              <li>Configure the server to serve the files in the <code>angular-phonecat</code>
+directory.</li>
+              <li>Navigate in your browser to
+<code>http://localhost:[port-number]/[context-path]/app/index.html</code>.</li>
+            </ol>
+          </li>
+        </ul>
+      </li>
+    </ol>
+  </div>
+
+
+  <div class="tab-pane well" id="git-win" title="Git on Windows" value="gitWin">
+    <ol>
+      <li><p>Open Git bash and run this command (in <code>angular-phonecat</code> directory):</p>
+      <pre>git checkout -f step-0</pre>
+      <p>This resets your workspace to step 0 of the tutorial app.</p>
+      <p>You must repeat this for every future step in the tutorial and change the number to
+      the number of the step you are on. This will cause any changes you made within
+      your working directory to be lost.</p></li>
+      <li>To see the app running in a browser, do one of the following:
+        <ul>
+          <li><b>For node.js users:</b>
+            <ol>
+              <li>In a <i>separate</i> terminal tab or window, run <code>node
+scripts\web-server.js</code> to start the web server.</li>
+              <li>Open a browser window for the app and navigate to <a
+href="http://localhost:8000/app/index.html">http://localhost:8000/app/index.html</a></li>
+            </ol>
+          </li>
+          <li><b>For other http servers:</b>
+            <ol>
+              <li>Configure the server to serve the files in the <code>angular-phonecat</code>
+directory.</li>
+              <li>Navigate in your browser to
+<code>http://localhost:[port-number]/[context-path]/app/index.html</code>.</li>
+            </ol>
+          </li>
+        </ul>
+      </li>
+    </ol>
+  </div>
+</div>
+
+
+You can now see the page in your browser. It's not very exciting, but that's OK.
+
+The HTML page that displays "Nothing here yet!" was constructed with the HTML code shown below.
+The code contains some key Angular elements that we will need going forward.
+
+__`app/index.html`:__
+<pre>
+<!doctype html>
+<html lang="en" ng-app>
+<head>
+  <meta charset="utf-8">
+  <title>My HTML File</title>
+  <link rel="stylesheet" href="css/app.css">
+  <link rel="stylesheet" href="css/bootstrap.css">
+  <script src="lib/angular/angular.js"></script>
+</head>
+<body>
+
+  <p>Nothing here {{'yet' + '!'}}</p>
+
+</body>
+</html>
+</pre>
+
+
+
+## What is the code doing?
+
+* `ng-app` directive:
+
+          <html ng-app>
+
+  The `ng-app` attribute represents an Angular directive (named `ngApp`; Angular uses
+  `name-with-dashes` for attribute names and `camelCase` for the corresponding directive name)
+  used to flag an element which Angular should consider to be the root element of our application.
+  This gives application developers the freedom to tell Angular if the entire html page or only a
+  portion of it should be treated as the Angular application.
+
+* AngularJS script tag:
+
+          <script src="lib/angular/angular.js">
+
+  This code downloads the `angular.js` script and registers a callback that will be executed by the
+browser when the containing HTML page is fully downloaded. When the callback is executed, Angular
+looks for the {@link api/ng.directive:ngApp ngApp} directive. If
+Angular finds the directive, it will bootstrap the application with the root of the application DOM
+being the element on which the `ngApp` directive was defined.
+
+* Double-curly binding with an expression:
+
+          Nothing here {{'yet' + '!'}}
+
+  This line demonstrates the core feature of Angular's templating capabilities – a binding, denoted
+  by double-curlies `{{ }}` as well as a simple expression `'yet' + '!'` used in this binding.
+
+  The binding tells Angular that it should evaluate an expression and insert the result into the
+  DOM in place of the binding. Rather than a one-time insert, as we'll see in the next steps, a
+  binding will result in efficient continuous updates whenever the result of the expression
+  evaluation changes.
+
+  {@link guide/expression Angular expression} is a JavaScript-like code snippet that is
+  evaluated by Angular in the context of the current model scope, rather than within the scope of
+  the global context (`window`).
+
+  As expected, once this template is processed by Angular, the html page contains the text:
+  "Nothing here yet!".
+
+## Bootstrapping AngularJS apps
+
+Bootstrapping AngularJS apps automatically using the `ngApp` directive is very easy and suitable
+for most cases. In advanced cases, such as when using script loaders, you can use
+{@link guide/bootstrap imperative / manual way} to bootstrap the app.
+
+There are 3 important things that happen during the app bootstrap:
+
+1. The {@link api/AUTO.$injector injector} that will be used for dependency injection
+   when this app is created.
+
+2. The injector will then create the {@link api/ng.$rootScope root scope} that will
+   become the context for the model of our application.
+
+3. Angular will then "compile" the DOM starting at the `ngApp` root element, processing any
+   directives and bindings found along the way.
+
+
+Once an application is bootstrapped, it will then wait for incoming browser events (such as mouse
+click, key press or incoming HTTP response) that might change the model. Once such an event occurs,
+Angular detects if it caused any model changes and if changes are found, Angular will reflect them
+in the view by updating all of the affected bindings.
+
+The structure of our application is currently very simple. The template contains just one directive
+and one static binding, and our model is empty. That will soon change!
+
+<img class="diagram" src="img/tutorial/tutorial_00.png">
+
+
+## What are all these files in my working directory?
+
+Most of the files in your working directory come from the {@link
+https://github.com/angular/angular-seed angular-seed project} which is typically used to bootstrap
+new Angular projects. The seed project includes the latest Angular libraries, test libraries,
+scripts and a simple example app, all pre-configured for developing a typical web app.
+
+For the purposes of this tutorial, we modified the angular-seed with the following changes:
+
+* Removed the example app
+* Added phone images to `app/img/phones/`
+* Added phone data files (JSON) to `app/phones/`
+* Added [Bootstrap](http://twitter.github.com/bootstrap/) files to `app/css/` and `app/img/`
+
+
+
+# Experiments
+
+* Try adding a new expression to the `index.html` that will do some math:
+
+          <p>1 + 2 = {{ 1 + 2 }}</p>
+
+
+
+# Summary
+
+Now let's go to {@link step_01 step 1} and add some content to the web app.
+
+
+<ul doc-tutorial-nav="0"></ul>
+
+<div style="display: none">
+Note: During the bootstrap the injector and the root scope will then be associated with the
+   element on which the `ngApp` directive was declared, so when debugging the app you can retrieve
+   them from browser console via `angular.element(rootElement).scope()` and
+   `angular.element(rootElement).injector()`.
+</div>
@@ -0,0 +1,55 @@
+@ngdoc overview
+@name Tutorial: 1 - Static Template
+@description
+
+<ul doc-tutorial-nav="1"></ul>
+
+
+In order to illustrate how Angular enhances standard HTML, you will create a purely *static* HTML
+page and then examine how we can turn this HTML code into a template that Angular will use to
+dynamically display the same result with any set of data.
+
+In this step you will add some basic information about two cell phones to an HTML page.
+
+
+<div doc-tutorial-reset="1"></div>
+
+
+The page now contains a list with information about two phones.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-0...step-1 GitHub}:
+
+__`app/index.html`:__
+<pre>
+  <ul>
+    <li>
+      <span>Nexus S</span>
+      <p>
+        Fast just got faster with Nexus S.
+      </p>
+    </li>
+    <li>
+      <span>Motorola XOOM™ with Wi-Fi</span>
+      <p>
+        The Next, Next Generation tablet.
+      </p>
+    </li>
+  </ul>
+</pre>
+
+
+# Experiments
+
+* Try adding more static HTML to `index.html`. For example:
+
+          <p>Total number of phones: 2</p>
+
+
+# Summary
+
+This addition to your app uses static HTML to display the list. Now, let's go to {@link step_02
+step 2} to learn how to use AngularJS to dynamically generate the same list.
+
+
+<ul doc-tutorial-nav="1"></ul>
@@ -0,0 +1,206 @@
+@ngdoc overview
+@name Tutorial: 2 - Angular Templates
+@description
+
+<ul doc-tutorial-nav="2"></ul>
+
+
+Now it's time to make the web page dynamic — with AngularJS. We'll also add a test that verifies the
+code for the controller we are going to add.
+
+There are many ways to structure the code for an application. For Angular apps, we encourage the
+use of {@link http://en.wikipedia.org/wiki/Model–View–Controller the Model-View-Controller (MVC)
+design pattern} to decouple the code and to separate concerns. With that in mind, let's use a
+little Angular and JavaScript to add model, view, and controller components to our app.
+
+
+<div doc-tutorial-reset="2"></div>
+
+
+The app now contains a list with three phones.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-1...step-2 GitHub}:
+
+
+## View and Template
+
+In Angular, the __view__ is a projection of the model through the HTML __template__. This means that
+whenever the model changes, Angular refreshes the appropriate binding points, which updates the
+view.
+
+The view component is constructed by Angular from this template:
+
+__`app/index.html`:__
+<pre>
+<html ng-app>
+<head>
+  ...
+  <script src="lib/angular/angular.js"></script>
+  <script src="js/controllers.js"></script>
+</head>
+<body ng-controller="PhoneListCtrl">
+
+  <ul>
+    <li ng-repeat="phone in phones">
+      {{phone.name}}
+      <p>{{phone.snippet}}</p>
+    </li>
+  </ul>
+</body>
+</html>
+</pre>
+
+We replaced the hard-coded phone list with the
+{@link api/ng.directive:ngRepeat ngRepeat directive} and two
+{@link guide/expression Angular expressions} enclosed in curly braces:
+`{{phone.name}}` and `{{phone.snippet}}`:
+
+* The `ng-repeat="phone in phones"` statement in the `<li>` tag is an Angular repeater. The
+repeater tells Angular to create a `<li>` element for each phone in the list using the first `<li>`
+tag as the template.
+
+* As we've learned in step 0, the curly braces around `phone.name` and `phone.snippet` denote
+bindings. As opposed to evaluating constants, these expressions are referring to our application
+model, which was set up in our `PhoneListCtrl` controller.
+
+      <img class="diagram" src="img/tutorial/tutorial_02.png">
+
+
+## Model and Controller
+
+The data __model__ (a simple array  of phones in object literal notation) is instantiated within
+the `PhoneListCtrl` __controller__:
+
+__`app/js/controllers.js`:__
+<pre>
+function PhoneListCtrl($scope) {
+  $scope.phones = [
+    {"name": "Nexus S",
+     "snippet": "Fast just got faster with Nexus S."},
+    {"name": "Motorola XOOM™ with Wi-Fi",
+     "snippet": "The Next, Next Generation tablet."},
+    {"name": "MOTOROLA XOOM™",
+     "snippet": "The Next, Next Generation tablet."}
+  ];
+}
+</pre>
+
+
+
+
+Although the controller is not yet doing very much controlling, it is playing a crucial role. By
+providing context for our data model, the controller allows us to establish data-binding between
+the model and the view. We connected the dots between the presentation, data, and logic components
+as follows:
+
+* `PhoneListCtrl` — the name of our controller function (located in the JavaScript file
+`controllers.js`), matches the value of the
+{@link api/ng.directive:ngController ngController} directive located
+on the `<body>` tag.
+
+* The phone data is then attached to the *scope* (`$scope`) that was injected into our controller
+function. The controller scope is a prototypical descendant of the root scope that was created
+when the application bootstrapped. This controller scope is available to all bindings located within
+the `<body ng-controller="PhoneListCtrl">` tag.
+
+  The concept of a scope in Angular is crucial; a scope can be seen as the glue which allows the
+template, model and controller to work together. Angular uses scopes, along with the information
+contained in the template, data model, and controller, to keep models and views separate, but in
+sync. Any changes made to the model are reflected in the view; any changes that occur in the view
+are reflected in the model.
+
+  To learn more about Angular scopes, see the {@link api/ng.$rootScope.Scope angular scope documentation}.
+
+
+## Tests
+
+The "Angular way" makes it easy to test code as it is being developed. Take a look at the following
+unit test for your newly created controller:
+
+__`test/unit/controllersSpec.js`:__
+<pre>
+describe('PhoneCat controllers', function() {
+
+  describe('PhoneListCtrl', function(){
+
+    it('should create "phones" model with 3 phones', function() {
+      var scope = {},
+          ctrl = new PhoneListCtrl(scope);
+
+      expect(scope.phones.length).toBe(3);
+    });
+  });
+});
+</pre>
+
+The test instantiates our PhoneListCtrl and verifies that its phones array property contains three
+records. This example demonstrates how easy it is to create a unit test for code in Angular. Since
+testing is such a critical part of software development, we make it easy to create tests in Angular
+so that developers are encouraged to write them.
+
+Angular developers prefer the syntax of Jasmine's Behavior-driven Development  (BDD) framework when
+writing tests. Although Angular does not require you to use Jasmine, we wrote all of the tests in
+this tutorial in Jasmine. You can learn about Jasmine on the {@link
+http://pivotal.github.com/jasmine/ Jasmine home page} and on the {@link
+https://github.com/pivotal/jasmine/wiki Jasmine wiki}.
+
+The angular-seed project is pre-configured to run all unit tests using {@link
+http://karma-runner.github.io/ Karma}. To run the test, do the following:
+
+1. In a _separate_ terminal window or tab, go to the `angular-phonecat` directory and run
+`./scripts/test.sh` to start the Karma server (the config file necessary to start the server
+is located at `./config/karma.conf.js`).
+
+2. Karma will start a new instance of Chrome browser automatically. Just ignore it and let it run in
+   the background. Karma will use this browser for test execution.
+
+3. You should see the following or similar output in the terminal:
+
+             info: Karma server started at http://localhost:9876/
+             info (launcher): Starting  browser "Chrome"
+             info (Chrome 22.0): Connected on socket id tPUm9DXcLHtZTKbAEO-n
+             Chrome 22.0: Executed 1 of 1 SUCCESS (0.093 secs / 0.004 secs)
+
+  Yay! The test passed! Or not...
+
+4. To rerun the tests, just change any of the source or test files. Karma will notice the change
+  and will rerun the tests for you. Now isn't that sweet?
+
+# Experiments
+
+* Add another binding to `index.html`. For example:
+
+          <p>Total number of phones: {{phones.length}}</p>
+
+* Create a new model property in the controller and bind to it from the template. For example:
+
+          $scope.hello = "Hello, World!"
+
+  Refresh your browser to make sure it says, "Hello, World!"
+
+* Create a repeater that constructs a simple table:
+
+          <table>
+            <tr><th>row number</th></tr>
+            <tr ng-repeat="i in [0, 1, 2, 3, 4, 5, 6, 7]"><td>{{i}}</td></tr>
+          </table>
+
+  Now, make the list 1-based by incrementing `i` by one in the binding:
+
+          <table>
+            <tr><th>row number</th></tr>
+            <tr ng-repeat="i in [0, 1, 2, 3, 4, 5, 6, 7]"><td>{{i+1}}</td></tr>
+          </table>
+
+* Make the unit test fail by changing the `toBe(3)` statement to `toBe(4)`.
+
+
+# Summary
+
+You now have a dynamic app that features separate model, view, and controller components, and you
+are testing as you go. Now, let's go to {@link step_03 step 3} to learn how to add full text search
+to the app.
+
+
+<ul doc-tutorial-nav="2"></ul>
@@ -0,0 +1,204 @@
+@ngdoc overview
+@name Tutorial: 3 - Filtering Repeaters
+@description
+
+<ul doc-tutorial-nav="3"></ul>
+
+
+We did a lot of work in laying a foundation for the app in the last step, so now we'll do something
+simple; we will add full text search (yes, it will be simple!). We will also write an end-to-end
+test, because a good end-to-end test is a good friend. It stays with your app, keeps an eye on it,
+and quickly detects regressions.
+
+
+<div doc-tutorial-reset="3"></div>
+
+
+The app now has a search box. Notice that the phone list on the page changes depending on what a
+user types into the search box.
+
+The most important differences between Steps 2 and 3 are listed below. You can see the full diff on
+{@link https://github.com/angular/angular-phonecat/compare/step-2...step-3
+ GitHub}:
+
+
+## Controller
+
+We made no changes to the controller.
+
+
+## Template
+
+__`app/index.html`:__
+<pre>
+  <div class="container-fluid">
+    <div class="row-fluid">
+      <div class="span2">
+        <!--Sidebar content-->
+
+        Search: <input ng-model="query">
+
+      </div>
+      <div class="span10">
+        <!--Body content-->
+
+        <ul class="phones">
+          <li ng-repeat="phone in phones | filter:query">
+            {{phone.name}}
+            <p>{{phone.snippet}}</p>
+          </li>
+        </ul>
+
+      </div>
+    </div>
+  </div>
+</pre>
+
+We added a standard HTML `<input>` tag and used Angular's
+{@link api/ng.filter:filter $filter} function to process the input for the
+{@link api/ng.directive:ngRepeat ngRepeat} directive.
+
+This lets a user enter search criteria and immediately see the effects of their search on the phone
+list. This new code demonstrates the following:
+
+* Data-binding: This is one of the core features in Angular. When the page loads, Angular binds the
+name of the input box to a variable of the same name in the data model and keeps the two in sync.
+
+  In this code, the data that a user types into the input box (named __`query`__) is immediately
+available as a filter input in the list repeater (`phone in phones | filter:`__`query`__). When
+changes to the data model cause the repeater's input to change, the repeater efficiently updates
+the DOM to reflect the current state of the model.
+
+<img  class="diagram" src="img/tutorial/tutorial_03.png">
+
+* Use of the `filter` filter: The {@link api/ng.filter:filter filter} function uses the
+`query` value to create a new array that contains only those records that match the `query`.
+
+  `ngRepeat` automatically updates the view in response to the changing number of phones returned
+by the `filter` filter. The process is completely transparent to the developer.
+
+## Test
+
+In Step 2, we learned how to write and run unit tests. Unit tests are perfect for testing
+controllers and other components of our application written in JavaScript, but they can't easily
+test DOM manipulation or the wiring of our application. For these, an end-to-end test is a much
+better choice.
+
+The search feature was fully implemented via templates and data-binding, so we'll write our first
+end-to-end test, to verify that the feature works.
+
+__`test/e2e/scenarios.js`:__
+<pre>
+describe('PhoneCat App', function() {
+
+  describe('Phone list view', function() {
+
+    beforeEach(function() {
+      browser().navigateTo('../../app/index.html');
+    });
+
+
+    it('should filter the phone list as user types into the search box', function() {
+      expect(repeater('.phones li').count()).toBe(3);
+
+      input('query').enter('nexus');
+      expect(repeater('.phones li').count()).toBe(1);
+
+      input('query').enter('motorola');
+      expect(repeater('.phones li').count()).toBe(2);
+    });
+  });
+});
+</pre>
+
+Even though the syntax of this test looks very much like our controller unit test written with
+Jasmine, the end-to-end test uses APIs of {@link guide/dev_guide.e2e-testing Angular's end-to-end
+test runner}.
+
+To run the end-to-end test, open one of the following in a new browser tab:
+
+* node.js users: {@link http://localhost:8000/test/e2e/runner.html}
+* users with other http servers:
+`http://localhost:[port-number]/[context-path]/test/e2e/runner.html`
+* casual reader: {@link http://angular.github.com/angular-phonecat/step-3/test/e2e/runner.html}
+
+Previously we've seen how Karma can be used to execute unit tests. Well, it can also run the
+end-to-end tests! Use `./scripts/e2e-test.sh` script for that. End-to-end tests are slow, so unlike
+with unit tests, Karma will exit after the test run and will not automatically rerun the test
+suite on every file change. To rerun the test suite, execute the `e2e-test.sh` script again.
+
+Note: You must ensure you've installed karma-ng-scenario prior to running the `e2e-test.sh` script.
+You can do this by issuing `npm install karma-ng-scenario` into your terminal.
+
+This test verifies that the search box and the repeater are correctly wired together. Notice how
+easy it is to write end-to-end tests in Angular. Although this example is for a simple test, it
+really is that easy to set up any functional, readable, end-to-end test.
+
+# Experiments
+
+* Display the current value of the `query` model by adding a `{{query}}` binding into the
+`index.html` template, and see how it changes when you type in the input box.
+
+* Let's see how we can get the current value of the `query` model to appear in the HTML page title.
+
+  You might think you could just add the `{{query}}` to the title tag element as follows:
+
+          <title>Google Phone Gallery: {{query}}</title>
+
+  However, when you reload the page, you won't see the expected result. This is because the "query"
+  model lives in the scope, defined by the `ng-controller="PhoneListCtrl"` directive, on the body element:
+
+          <body ng-controller="PhoneListCtrl">
+
+  If you want to bind to the query model from the `<title>` element, you must __move__ the
+`ngController` declaration to the HTML element because it is the common parent of both the body
+and title elements:
+
+          <html ng-app ng-controller="PhoneListCtrl">
+
+  Be sure to __remove__ the `ng-controller` declaration from the body element.
+
+  While using double curlies works fine within the title element, you might have noticed that
+for a split second they are actually displayed to the user while the page is loading. A better
+solution would be to use the {@link api/ng.directive:ngBind
+ngBind} or {@link api/ng.directive:ngBindTemplate
+ngBindTemplate} directives, which are invisible to the user while the page is loading:
+
+          <title ng-bind-template="Google Phone Gallery: {{query}}">Google Phone Gallery</title>
+
+* Add the following end-to-end test into the `describe` block within `test/e2e/scenarios.js`:
+
+  <pre>
+    it('should display the current filter value within an element with id "status"',
+        function() {
+      expect(element('#status').text()).toMatch(/Current filter: \s*$/);
+
+      input('query').enter('nexus');
+
+      expect(element('#status').text()).toMatch(/Current filter: nexus\s*$/);
+
+      //alternative version of the last assertion that tests just the value of the binding
+      using('#status').expect(binding('query')).toBe('nexus');
+    });
+  </pre>
+
+  Refresh the browser tab with the end-to-end test runner to see the test fail. To make the test
+pass, edit the `index.html` template to add a `div` or `p` element with `id` `"status"` and content
+with the `query` binding, prefixed by "Current filter:". For instance:
+
+          <div id="status">Current filter: {{query}}</div>
+
+* Add a `pause()` statement inside of an end-to-end test and rerun it. You'll see the runner pause;
+this gives you the opportunity to explore the state of your application while it is displayed in
+the browser. The app is live! You can change the search query to prove it. Notice how useful this
+is for troubleshooting end-to-end tests.
+
+
+# Summary
+
+We have now added full text search and included a test to verify that search works! Now let's go on
+to {@link step_04 step 4} to learn how to add sorting capability to the phone app.
+
+
+<ul doc-tutorial-nav="3"></ul>
+
@@ -0,0 +1,189 @@
+@ngdoc overview
+@name Tutorial: 4 - Two-way Data Binding
+@description
+
+<ul doc-tutorial-nav="4"></ul>
+
+
+In this step, you will add a feature to let your users control the order of the items in the phone
+list. The dynamic ordering is implemented by creating a new model property, wiring it together with
+the repeater, and letting the data binding magic do the rest of the work.
+
+
+<div doc-tutorial-reset="4"></div>
+
+
+You should see that in addition to the search box, the app displays a drop down menu that allows
+users to control the order in which the phones are listed.
+
+The most important differences between Steps 3 and 4 are listed below. You can see the full diff on
+{@link https://github.com/angular/angular-phonecat/compare/step-3...step-4 GitHub}:
+
+
+## Template
+
+__`app/index.html`:__
+<pre>
+  Search: <input ng-model="query">
+  Sort by:
+  <select ng-model="orderProp">
+    <option value="name">Alphabetical</option>
+    <option value="age">Newest</option>
+  </select>
+
+
+  <ul class="phones">
+    <li ng-repeat="phone in phones | filter:query | orderBy:orderProp">
+      {{phone.name}}
+      <p>{{phone.snippet}}</p>
+    </li>
+  </ul>
+</pre>
+
+We made the following changes to the `index.html` template:
+
+* First, we added a `<select>` html element named `orderProp`, so that our users can pick from the
+two provided sorting options.
+
+<img class="diagram" src="img/tutorial/tutorial_04.png">
+
+* We then chained the `filter` filter with {@link api/ng.filter:orderBy `orderBy`}
+filter to further process the input into the repeater. `orderBy` is a filter that takes an input
+array, copies it and reorders the copy which is then returned.
+
+Angular creates a two way data-binding between the select element and the `orderProp` model.
+`orderProp` is then used as the input for the `orderBy` filter.
+
+As we discussed in the section about data-binding and the repeater in step 3, whenever the model
+changes (for example because a user changes the order with the select drop down menu), Angular's
+data-binding will cause the view to automatically update. No bloated DOM manipulation code is
+necessary!
+
+
+
+## Controller
+
+__`app/js/controllers.js`:__
+<pre>
+function PhoneListCtrl($scope) {
+  $scope.phones = [
+    {"name": "Nexus S",
+     "snippet": "Fast just got faster with Nexus S.",
+     "age": 0},
+    {"name": "Motorola XOOM™ with Wi-Fi",
+     "snippet": "The Next, Next Generation tablet.",
+     "age": 1},
+    {"name": "MOTOROLA XOOM™",
+     "snippet": "The Next, Next Generation tablet.",
+     "age": 2}
+  ];
+
+  $scope.orderProp = 'age';
+}
+</pre>
+
+* We modified the `phones` model - the array of phones - and added an `age` property to each phone
+record. This property is used to order phones by age.
+
+* We added a line to the controller that sets the default value of `orderProp` to `age`. If we had
+not set the default value here, the model would stay uninitialized until our user would pick an
+option from the drop down menu.
+
+  This is a good time to talk about two-way data-binding. Notice that when the app is loaded in the
+browser, "Newest" is selected in the drop down menu. This is because we set `orderProp` to `'age'`
+in the controller. So the binding works in the direction from our model to the UI. Now if you
+select "Alphabetically" in the drop down menu, the model will be updated as well and the phones
+will be reordered. That is the data-binding doing its job in the opposite direction — from the UI
+to the model.
+
+
+
+## Test
+
+The changes we made should be verified with both a unit test and an end-to-end test. Let's look at
+the unit test first.
+
+__`test/unit/controllersSpec.js`:__
+<pre>
+describe('PhoneCat controllers', function() {
+
+  describe('PhoneListCtrl', function(){
+    var scope, ctrl;
+
+    beforeEach(function() {
+      scope = {},
+      ctrl = new PhoneListCtrl(scope);
+    });
+
+
+    it('should create "phones" model with 3 phones', function() {
+      expect(scope.phones.length).toBe(3);
+    });
+
+
+    it('should set the default value of orderProp model', function() {
+      expect(scope.orderProp).toBe('age');
+    });
+  });
+});
+</pre>
+
+
+The unit test now verifies that the default ordering property is set.
+
+We used Jasmine's API to extract the controller construction into a `beforeEach` block, which is
+shared by all tests in the parent `describe` block.
+
+You should now see the following output in the Karma tab:
+
+        Chrome 22.0: Executed 2 of 2 SUCCESS (0.021 secs / 0.001 secs)
+
+
+Let's turn our attention to the end-to-end test.
+
+__`test/e2e/scenarios.js`:__
+<pre>
+...
+    it('should be possible to control phone order via the drop down select box',
+        function() {
+      //let's narrow the dataset to make the test assertions shorter
+      input('query').enter('tablet');
+
+      expect(repeater('.phones li', 'Phone List').column('phone.name')).
+          toEqual(["Motorola XOOM\u2122 with Wi-Fi",
+                   "MOTOROLA XOOM\u2122"]);
+
+      select('orderProp').option('Alphabetical');
+
+      expect(repeater('.phones li', 'Phone List').column('phone.name')).
+          toEqual(["MOTOROLA XOOM\u2122",
+                   "Motorola XOOM\u2122 with Wi-Fi"]);
+    });
+...
+</pre>
+
+The end-to-end test verifies that the ordering mechanism of the select box is working correctly.
+
+You can now rerun `./scripts/e2e-test.sh` or refresh the browser tab with the end-to-end test
+`runner.html` to see the tests run, or you can see them running on {@link
+http://angular.github.com/angular-phonecat/step-4/test/e2e/runner.html
+Angular's server}.
+
+# Experiments
+
+* In the `PhoneListCtrl` controller, remove the statement that sets the `orderProp` value and
+you'll see that Angular will temporarily add a new "unknown" option to the drop-down list and the
+ordering will default to unordered/natural order.
+
+* Add an `{{orderProp}}` binding into the `index.html` template to display its current value as
+text.
+
+* Reverse the sort order by adding a `-` symbol before the sorting value: `<option value="-age">Oldest</option>`
+
+# Summary
+
+Now that you have added list sorting and tested the app, go to {@link step_05 step 5} to learn
+about Angular services and how Angular uses dependency injection.
+
+
+<ul doc-tutorial-nav="4"></ul>
@@ -0,0 +1,236 @@
+@ngdoc overview
+@name Tutorial: 5 - XHRs & Dependency Injection
+@description
+
+<ul doc-tutorial-nav="5"></ul>
+
+
+Enough of building an app with three phones in a hard-coded dataset! Let's fetch a larger dataset
+from our server using one of angular's built-in {@link api/ng services} called {@link
+api/ng.$http $http}. We will use angular's {@link guide/di dependency
+injection (DI)} to provide the service to the `PhoneListCtrl` controller.
+
+
+<div doc-tutorial-reset="5"></div>
+
+
+You should now see a list of 20 phones.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-4...step-5
+GitHub}:
+
+## Data
+
+The `app/phones/phones.json` file in your project is a dataset that contains a larger list of phones
+stored in the JSON format.
+
+Following is a sample of the file:
+<pre>
+[
+ {
+  "age": 13,
+  "id": "motorola-defy-with-motoblur",
+  "name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
+  "snippet": "Are you ready for everything life throws your way?"
+  ...
+ },
+...
+]
+</pre>
+
+
+## Controller
+
+We'll use angular's {@link api/ng.$http $http} service in our controller to make an HTTP
+request to your web server to fetch the data in the `app/phones/phones.json` file. `$http` is just
+one of several built-in {@link guide/dev_guide.services angular services} that handle common operations
+in web apps. Angular injects these services for you where you need them.
+
+Services are managed by angular's {@link guide/di DI subsystem}. Dependency injection
+helps to make your web apps both well-structured (e.g., separate components for presentation, data,
+and control) and loosely coupled (dependencies between components are not resolved by the
+components themselves, but by the DI subsystem).
+
+__`app/js/controllers.js:`__
+<pre>
+function PhoneListCtrl($scope, $http) {
+  $http.get('phones/phones.json').success(function(data) {
+    $scope.phones = data;
+  });
+
+  $scope.orderProp = 'age';
+}
+
+//PhoneListCtrl.$inject = ['$scope', '$http'];
+</pre>
+
+`$http` makes an HTTP GET request to our web server, asking for `phone/phones.json` (the url is
+relative to our `index.html` file). The server responds by providing the data in the json file.
+(The response might just as well have been dynamically generated by a backend server. To the
+browser and our app they both look the same. For the sake of simplicity we used a json file in this
+tutorial.)
+
+The `$http` service returns a {@link api/ng.$q promise object} with a `success`
+method. We call this method to handle the asynchronous response and assign the phone data to the
+scope controlled by this controller, as a model called `phones`. Notice that angular detected the
+json response and parsed it for us!
+
+To use a service in angular, you simply declare the names of the dependencies you need as arguments
+to the controller's constructor function, as follows:
+
+    function PhoneListCtrl($scope, $http) {...}
+
+Angular's dependency injector provides services to your controller when the controller is being
+constructed. The dependency injector also takes care of creating any transitive dependencies the
+service may have (services often depend upon other services).
+
+Note that the names of arguments are significant, because the injector uses these to look up the
+dependencies.
+
+
+<img  class="diagram" src="img/tutorial/xhr_service_final.png">
+
+
+### '$' Prefix Naming Convention
+
+You can create your own services, and in fact we will do exactly that in step 11. As a naming
+convention, angular's built-in services, Scope methods and a few other angular APIs have a '$'
+prefix in front of the name.  Don't use a '$' prefix when naming your services and models, in order
+to avoid any possible naming collisions.
+
+### A Note on Minification
+
+Since angular infers the controller's dependencies from the names of arguments to the controller's
+constructor function, if you were to {@link http://en.wikipedia.org/wiki/Minification_(programming)
+minify} the JavaScript code for `PhoneListCtrl` controller, all of its function arguments would be
+minified as well, and the dependency injector would not be able to identify services correctly.
+
+To overcome issues caused by minification, just assign an array with service identifier strings
+into the `$inject` property of the controller function, just like the last line in the snippet
+(commented out) suggests:
+
+    PhoneListCtrl.$inject = ['$scope', '$http'];
+
+There is also one more way to specify this dependency list and avoid minification issues — using the
+bracket notation which wraps the function to be injected into an array of strings (representing the
+dependency names) followed by the function to be injected:
+
+    var PhoneListCtrl = ['$scope', '$http', function($scope, $http) { /* constructor body */ }];
+
+Both of these methods work with any function that can be injected by Angular, so it's up to your
+project's style guide to decide which one you use.
+
+
+## Test
+
+__`test/unit/controllersSpec.js`:__
+
+Because we started using dependency injection and our controller has dependencies, constructing the
+controller in our tests is a bit more complicated. We could use the `new` operator and provide the
+constructor with some kind of fake `$http` implementation. However, the recommended (and easier) way
+is to create a controller in the test environment in the same way that angular does it in the
+production code behind the scenes, as follows:
+
+<pre>
+describe('PhoneCat controllers', function() {
+
+  describe('PhoneListCtrl', function(){
+    var scope, ctrl, $httpBackend;
+
+    // The injector ignores leading and trailing underscores here (i.e. _$httpBackend_).
+    // This allows us to inject a service but then attach it to a variable
+    // with the same name as the service.
+    beforeEach(inject(function(_$httpBackend_, $rootScope, $controller) {
+      $httpBackend = _$httpBackend_;
+      $httpBackend.expectGET('phones/phones.json').
+          respond([{name: 'Nexus S'}, {name: 'Motorola DROID'}]);
+
+      scope = $rootScope.$new();
+      ctrl = $controller(PhoneListCtrl, {$scope: scope});
+    }));
+</pre>
+
+Note: Because we loaded Jasmine and `angular-mocks.js` in our test environment, we got two helper
+methods {@link api/angular.mock.module module} and {@link api/angular.mock.inject inject} that we'll
+use to access and configure the injector.
+
+We created the controller in the test environment, as follows:
+
+* We used the `inject` helper method to inject instances of
+{@link api/ng.$rootScope $rootScope},
+{@link api/ng.$controller $controller} and
+{@link api/ng.$httpBackend $httpBackend} services into the Jasmine's `beforeEach`
+function. These instances come from an injector which is recreated from scratch for every single
+test. This guarantees that each test starts from a well known starting point and each test is
+isolated from the work done in other tests.
+
+* We created a new scope for our controller by calling `$rootScope.$new()`
+
+* We called the injected `$controller` function passing the `PhoneListCtrl` function and the created
+scope as parameters.
+
+Because our code now uses the `$http` service to fetch the phone list data in our controller, before
+we create the `PhoneListCtrl` child scope, we need to tell the testing harness to expect an
+incoming request from the controller. To do this we:
+
+* Request `$httpBackend` service to be injected into our `beforeEach` function. This is a mock
+version of the service that in a production environment facilitates all XHR and JSONP requests.
+The mock version of this service allows you to write tests without having to deal with
+native APIs and the global state associated with them — both of which make testing a nightmare.
+
+* Use the `$httpBackend.expectGET` method to train the `$httpBackend` service to expect an incoming
+HTTP request and tell it what to respond with. Note that the responses are not returned until we call
+the `$httpBackend.flush` method.
+
+Now, we will make assertions to verify that the `phones` model doesn't exist on `scope` before
+the response is received:
+
+<pre>
+    it('should create "phones" model with 2 phones fetched from xhr', function() {
+      expect(scope.phones).toBeUndefined();
+      $httpBackend.flush();
+
+      expect(scope.phones).toEqual([{name: 'Nexus S'},
+                                   {name: 'Motorola DROID'}]);
+    });
+</pre>
+
+* We flush the request queue in the browser by calling `$httpBackend.flush()`. This causes the
+promise returned by the `$http` service to be resolved with the trained response.
+
+* We make the assertions, verifying that the phone model now exists on the scope.
+
+Finally, we verify that the default value of `orderProp` is set correctly:
+
+<pre>
+    it('should set the default value of orderProp model', function() {
+      expect(scope.orderProp).toBe('age');
+    });
+</pre>
+
+You should now see the following output in the Karma tab:
+
+       Chrome 22.0: Executed 2 of 2 SUCCESS (0.028 secs / 0.007 secs)
+
+
+
+# Experiments
+
+* At the bottom of `index.html`, add a `{{phones | json}}` binding to see the list of phones
+  displayed in json format.
+
+* In the `PhoneListCtrl` controller, pre-process the http response by limiting the number of phones
+to the first 5 in the list. Use the following code in the $http callback:
+
+         $scope.phones = data.splice(0, 5);
+
+
+# Summary
+
+Now that you have learned how easy it is to use angular services (thanks to Angular's dependency
+injection), go to {@link step_06 step 6}, where you will add some
+thumbnail images of phones and some links.
+
+
+<ul doc-tutorial-nav="5"></ul>
@@ -0,0 +1,111 @@
+@ngdoc overview
+@name Tutorial: 6 - Templating Links & Images
+@description
+
+<ul doc-tutorial-nav="6"></ul>
+
+
+In this step, you will add thumbnail images for the phones in the phone list, and links that, for
+now, will go nowhere. In subsequent steps you will use the links to display additional information
+about the phones in the catalog.
+
+
+<div doc-tutorial-reset="6"></div>
+
+
+You should now see links and images of the phones in the list.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-5...step-6
+GitHub}:
+
+
+## Data
+
+Note that the `phones.json` file contains unique ids and image urls for each of the phones. The
+urls point to the `app/img/phones/` directory.
+
+__`app/phones/phones.json`__ (sample snippet):
+<pre>
+ [
+  {
+   ...
+   "id": "motorola-defy-with-motoblur",
+   "imageUrl": "img/phones/motorola-defy-with-motoblur.0.jpg",
+   "name": "Motorola DEFY\u2122 with MOTOBLUR\u2122",
+   ...
+  },
+ ...
+ ]
+</pre>
+
+
+## Template
+
+__`app/index.html`:__
+<pre>
+...
+        <ul class="phones">
+          <li ng-repeat="phone in phones | filter:query | orderBy:orderProp" class="thumbnail">
+            <a href="#/phones/{{phone.id}}" class="thumb"><img ng-src="{{phone.imageUrl}}"></a>
+            <a href="#/phones/{{phone.id}}">{{phone.name}}</a>
+            <p>{{phone.snippet}}</p>
+          </li>
+        </ul>
+...
+</pre>
+
+To dynamically generate links that will in the future lead to phone detail pages, we used the
+now-familiar double-curly brace binding in the `href` attribute values. In step 2, we added the
+`{{phone.name}}` binding as the element content. In this step the `{{phone.id}}` binding is used in
+the element attribute.
+
+We also added phone images next to each record using an image tag with the {@link
+api/ng.directive:ngSrc ngSrc} directive. That directive prevents the
+browser from treating the angular `{{ expression }}` markup literally, and initiating a request to
+invalid url `http://localhost:8000/app/{{phone.imageUrl}}`, which it would have done if we had only
+specified an attribute binding in a regular `src` attribute (`<img  class="diagram" src="{{phone.imageUrl}}">`).
+Using the `ngSrc` directive prevents the browser from making an http request to an invalid location.
+
+
+## Test
+
+__`test/e2e/scenarios.js`__:
+<pre>
+...
+    it('should render phone specific links', function() {
+      input('query').enter('nexus');
+      element('.phones li a').click();
+      expect(browser().location().url()).toBe('/phones/nexus-s');
+    });
+...
+</pre>
+
+We added a new end-to-end test to verify that the app is generating correct links to the phone
+views that we will implement in the upcoming steps.
+
+You can now rerun `./scripts/e2e-test.sh` or refresh the browser tab with the end-to-end test
+runner to see the tests run, or you can see them running on {@link
+http://angular.github.com/angular-phonecat/step-6/test/e2e/runner.html
+Angular's server}.
+
+
+# Experiments
+
+* Replace the `ng-src` directive with a plain old `src` attribute. Using tools such as Firebug,
+or Chrome's Web Inspector, or inspecting the webserver access logs, confirm that the app is indeed
+making an extraneous request to `/app/%7B%7Bphone.imageUrl%7D%7D` (or
+`/app/{{phone.imageUrl}}`).
+
+  The issue here is that the browser will fire a request for that invalid image address as soon as
+it hits the `img` tag, which is before Angular has a chance to evaluate the expression and inject
+the valid address.
+
+
+# Summary
+
+Now that you have added phone images and links, go to {@link step_07 step 7} to learn about Angular
+layout templates and how Angular makes it easy to create applications that have multiple views.
+
+
+<ul doc-tutorial-nav="6"></ul>
@@ -0,0 +1,262 @@
+@ngdoc overview
+@name Tutorial: 7 - Routing & Multiple Views
+@description
+
+<ul doc-tutorial-nav="7"></ul>
+
+
+In this step, you will learn how to create a layout template and how to build an app that has
+multiple views by adding routing.
+
+
+<div doc-tutorial-reset="7"></div>
+
+
+Note that when you now navigate to `app/index.html`, you are redirected to `app/index.html#/phones`
+and the same phone list appears in the browser. When you click on a phone link the stub of a phone
+detail page is displayed.
+
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-6...step-7
+GitHub}.
+
+
+## Multiple Views, Routing and Layout Template
+
+Our app is slowly growing and becoming more complex. Before step 7, the app provided our users with
+a single view (the list of all phones), and all of the template code was located in the
+`index.html` file. The next step in building the app is to add a view that will show detailed
+information about each of the devices in our list.
+
+To add the detailed view, we could expand the `index.html` file to contain template code for both
+views, but that would get messy very quickly. Instead, we are going to turn the `index.html`
+template into what we call a "layout template". This is a template that is common for all views in
+our application. Other "partial templates" are then included into this layout template depending on
+the current "route" — the view that is currently displayed to the user.
+
+Application routes in Angular are declared via the
+{@link api/ng.$routeProvider $routeProvider}, which is the provider of the
+{@link api/ng.$route $route service}. This service makes it easy to wire together
+controllers, view templates, and the current
+URL location in the browser. Using this feature we can implement {@link
+http://en.wikipedia.org/wiki/Deep_linking deep linking}, which lets us utilize the browser's
+history (back and forward navigation) and bookmarks.
+
+
+### A Note About DI, Injector and Providers
+
+As you {@link tutorial/step_05 noticed}, {@link guide/di dependency injection} (DI) is the core feature of
+AngularJS, so it's important for you to understand a thing or two about how it works.
+
+When the application bootstraps, Angular creates an injector that will be used for all DI stuff in
+this app. The injector itself doesn't know anything about what `$http` or `$route` services do, in
+fact it doesn't even know about the existence of these services unless it is configured with proper
+module definitions. The sole responsibilities of the injector are to load specified module
+definition(s), register all service providers defined in these modules, and when asked, inject
+a specified function with dependencies (services) that it lazily instantiates via their providers.
+
+Providers are objects that provide (create) instances of services and expose configuration APIs
+that can be used to control the creation and runtime behavior of a service. In case of the `$route`
+service, the `$routeProvider` exposes APIs that allow you to define routes for your application.
+
+Angular modules solve the problem of removing global state from the application and provide a way
+of configuring the injector. As opposed to AMD or require.js modules, Angular modules don't try to
+solve the problem of script load ordering or lazy script fetching. These goals are orthogonal and
+both module systems can live side by side and fulfil their goals.
+
+## The App Module
+
+__`app/js/app.js`:__
+<pre>
+angular.module('phonecat', []).
+  config(['$routeProvider', function($routeProvider) {
+  $routeProvider.
+      when('/phones', {templateUrl: 'partials/phone-list.html',   controller: PhoneListCtrl}).
+      when('/phones/:phoneId', {templateUrl: 'partials/phone-detail.html', controller: PhoneDetailCtrl}).
+      otherwise({redirectTo: '/phones'});
+}]);
+</pre>
+
+In order to configure our application with routes, we need to create a module for our application.
+We call this module `phonecat` and using the `config` API we request the `$routeProvider` to be
+injected into our config function and use `$routeProvider.when` API to define our routes.
+
+Note that during the injector configuration phase, the providers can be injected as well, but they
+will not be available for injection once the injector is created and starts creating service
+instances.
+
+Our application routes were defined as follows:
+
+* The phone list view will be shown when the URL hash fragment is `/phones`. To construct this
+view, Angular will use the `phone-list.html` template and the `PhoneListCtrl` controller.
+
+* The phone details view will be shown when the URL hash fragment matches '/phone/:phoneId', where
+`:phoneId` is a variable part of the URL. To construct the phone details view, angular will use the
+`phone-detail.html` template and the `PhoneDetailCtrl` controller.
+
+We reused the `PhoneListCtrl` controller that we constructed in previous steps and we added a new,
+empty `PhoneDetailCtrl` controller to the `app/js/controllers.js` file for the phone details view.
+
+The statement `$route.otherwise({redirectTo: '/phones'})` triggers a redirection to `/phones` when
+the browser address doesn't match either of our routes.
+
+Note the use of the `:phoneId` parameter in the second route declaration. The `$route` service uses
+the route declaration — `'/phones/:phoneId'` — as a template that is matched against the current
+URL. All variables defined with the `:` notation are extracted into the
+{@link api/ng.$routeParams $routeParams} object.
+
+
+In order for our application to bootstrap with our newly created module we'll also need to specify
+the module name as the value of the {@link api/ng.directive:ngApp ngApp}
+directive:
+
+__`app/index.html`:__
+<pre>
+<!doctype html>
+<html lang="en" ng-app="phonecat">
+...
+</pre>
+
+
+## Controllers
+
+__`app/js/controllers.js`:__
+<pre>
+...
+function PhoneDetailCtrl($scope, $routeParams) {
+  $scope.phoneId = $routeParams.phoneId;
+}
+
+//PhoneDetailCtrl.$inject = ['$scope', '$routeParams'];
+</pre>
+
+
+## Template
+
+The `$route` service is usually used in conjunction with the {@link api/ng.directive:ngView
+ngView} directive. The role of the `ngView` directive is to include the view template for the current
+route into the layout template, which makes it a perfect fit for our `index.html` template.
+
+__`app/index.html`:__
+<pre>
+<html lang="en" ng-app="phonecat">
+<head>
+...
+  <script src="lib/angular/angular.js"></script>
+  <script src="js/app.js"></script>
+  <script src="js/controllers.js"></script>
+</head>
+<body>
+
+  <div ng-view></div>
+
+</body>
+</html>
+</pre>
+
+Note that we removed most of the code in the `index.html` template and replaced it with a single
+line containing a div with the `ng-view` attribute. The code that we removed was placed into the
+`phone-list.html` template:
+
+__`app/partials/phone-list.html`:__
+<pre>
+<div class="container-fluid">
+  <div class="row-fluid">
+    <div class="span2">
+      <!--Sidebar content-->
+
+      Search: <input ng-model="query">
+      Sort by:
+      <select ng-model="orderProp">
+        <option value="name">Alphabetical</option>
+        <option value="age">Newest</option>
+      </select>
+
+    </div>
+    <div class="span10">
+      <!--Body content-->
+
+      <ul class="phones">
+        <li ng-repeat="phone in phones | filter:query | orderBy:orderProp" class="thumbnail">
+          <a href="#/phones/{{phone.id}}" class="thumb"><img ng-src="{{phone.imageUrl}}"></a>
+          <a href="#/phones/{{phone.id}}">{{phone.name}}</a>
+          <p>{{phone.snippet}}</p>
+        </li>
+      </ul>
+
+    </div>
+  </div>
+</div>
+</pre>
+
+<div style="display:none">
+TODO!
+<img  class="diagram" src="img/tutorial/tutorial_07_final.png">
+</div>
+
+We also added a placeholder template for the phone details view:
+
+__`app/partials/phone-detail.html`:__
+<pre>
+TBD: detail view for {{phoneId}}
+</pre>
+
+Note how we are using `phoneId` model defined in the `PhoneDetailCtrl` controller.
+
+
+## Test
+
+To automatically verify that everything is wired properly, we wrote end-to-end tests that navigate
+to various URLs and verify that the correct view was rendered.
+
+<pre>
+...
+  it('should redirect index.html to index.html#/phones', function() {
+    browser().navigateTo('../../app/index.html');
+    expect(browser().location().url()).toBe('/phones');
+  });
+...
+
+ describe('Phone detail view', function() {
+
+    beforeEach(function() {
+      browser().navigateTo('../../app/index.html#/phones/nexus-s');
+    });
+
+
+    it('should display placeholder page with phoneId', function() {
+      expect(binding('phoneId')).toBe('nexus-s');
+    });
+ });
+</pre>
+
+
+You can now rerun `./scripts/e2e-test.sh` or refresh the browser tab with the end-to-end test
+runner to see the tests run, or you can see them running on {@link
+http://angular.github.com/angular-phonecat/step-7/test/e2e/runner.html
+Angular's server}.
+
+
+# Experiments
+
+* Try to add an `{{orderProp}}` binding to `index.html`, and you'll see that nothing happens even
+when you are in the phone list view. This is because the `orderProp` model is visible only in the
+scope managed by `PhoneListCtrl`, which is associated with the `<div ng-view>` element. If you add
+the same binding into the `phone-list.html` template, the binding will work as expected.
+
+<div style="display: none">
+* In `PhoneCatCtrl`, create a new model called "`hero`" with `this.hero = 'Zoro'`. In
+`PhoneListCtrl` let's shadow it with `this.hero = 'Batman'`, and in `PhoneDetailCtrl` we'll use
+`this.hero = "Captain Proton"`. Then add the `<p>hero = {{hero}}</p>` to all three of our templates
+(`index.html`, `phone-list.html`, and `phone-detail.html`). Open the app and you'll see scope
+inheritance and model property shadowing do some wonders.
+</div>
+
+# Summary
+
+With the routing set up and the phone list view implemented, we're ready to go to {@link step_08
+step 8} to implement the phone details view.
+
+
+<ul doc-tutorial-nav="7"></ul>
@@ -0,0 +1,194 @@
+@ngdoc overview
+@name Tutorial: 8 - More Templating
+@description
+
+<ul doc-tutorial-nav="8"></ul>
+
+
+In this step, you will implement the phone details view, which is displayed when a user clicks on a
+phone in the phone list.
+
+
+<div doc-tutorial-reset="8"></div>
+
+
+Now when you click on a phone on the list, the phone details page with phone-specific information
+is displayed.
+
+To implement the phone details view we will use {@link api/ng.$http $http} to fetch
+our data, and we'll flesh out the `phone-detail.html` view template.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-7...step-8
+GitHub}:
+
+## Data
+
+In addition to `phones.json`, the `app/phones/` directory also contains one json file for each
+phone:
+
+__`app/phones/nexus-s.json`:__ (sample snippet)
+<pre>
+{
+  "additionalFeatures": "Contour Display, Near Field Communications (NFC),...",
+  "android": {
+      "os": "Android 2.3",
+      "ui": "Android"
+  },
+  ...
+  "images": [
+      "img/phones/nexus-s.0.jpg",
+      "img/phones/nexus-s.1.jpg",
+      "img/phones/nexus-s.2.jpg",
+      "img/phones/nexus-s.3.jpg"
+  ],
+  "storage": {
+      "flash": "16384MB",
+      "ram": "512MB"
+  }
+}
+</pre>
+
+
+Each of these files describes various properties of the phone using the same data structure. We'll
+show this data in the phone detail view.
+
+
+## Controller
+
+We'll expand the `PhoneDetailCtrl` by using the `$http` service to fetch the json files. This works
+the same way as the phone list controller.
+
+__`app/js/controllers.js`:__
+<pre>
+function PhoneDetailCtrl($scope, $routeParams, $http) {
+  $http.get('phones/' + $routeParams.phoneId + '.json').success(function(data) {
+    $scope.phone = data;
+  });
+}
+
+//PhoneDetailCtrl.$inject = ['$scope', '$routeParams', '$http'];
+</pre>
+
+To construct the URL for the HTTP request, we use `$routeParams.phoneId` extracted from the current
+route by the `$route` service.
+
+
+## Template
+
+The TBD placeholder line has been replaced with lists and bindings that comprise the phone details.
+Note where we use the angular `{{expression}}` markup and `ngRepeat` to project phone data from
+our model into the view.
+
+
+__`app/partials/phone-detail.html`:__
+<pre>
+<img ng-src="{{phone.images[0]}}" class="phone">
+
+<h1>{{phone.name}}</h1>
+
+<p>{{phone.description}}</p>
+
+<ul class="phone-thumbs">
+  <li ng-repeat="img in phone.images">
+    <img ng-src="{{img}}">
+  </li>
+</ul>
+
+<ul class="specs">
+  <li>
+    <span>Availability and Networks</span>
+    <dl>
+      <dt>Availability</dt>
+      <dd ng-repeat="availability in phone.availability">{{availability}}</dd>
+    </dl>
+  </li>
+    ...
+  </li>
+    <span>Additional Features</span>
+    <dd>{{phone.additionalFeatures}}</dd>
+  </li>
+</ul>
+</pre>
+
+<div style="display: none">
+TODO!
+<img  class="diagram" src="img/tutorial/tutorial_08-09_final.png">
+</div>
+
+## Test
+
+We wrote a new unit test that is similar to the one we wrote for the `PhoneListCtrl` controller in
+step 5.
+
+__`test/unit/controllersSpec.js`:__
+<pre>
+...
+  describe('PhoneDetailCtrl', function(){
+    var scope, $httpBackend, ctrl;
+
+    beforeEach(inject(function(_$httpBackend_, $rootScope, $routeParams, $controller) {
+      $httpBackend = _$httpBackend_;
+      $httpBackend.expectGET('phones/xyz.json').respond({name:'phone xyz'});
+
+      $routeParams.phoneId = 'xyz';
+      scope = $rootScope.$new();
+      ctrl = $controller(PhoneDetailCtrl, {$scope: scope});
+    }));
+
+
+    it('should fetch phone detail', function() {
+      expect(scope.phone).toBeUndefined();
+      $httpBackend.flush();
+
+      expect(scope.phone).toEqual({name:'phone xyz'});
+    });
+  });
+...
+</pre>
+
+You should now see the following output in the Karma tab:
+
+    Chrome 22.0: Executed 3 of 3 SUCCESS (0.039 secs / 0.012 secs)
+
+
+We also added a new end-to-end test that navigates to the Nexus S detail page and verifies that the
+heading on the page is "Nexus S".
+
+__`test/e2e/scenarios.js`:__
+<pre>
+...
+  describe('Phone detail view', function() {
+
+    beforeEach(function() {
+      browser().navigateTo('../../app/index.html#/phones/nexus-s');
+    });
+
+
+    it('should display nexus-s page', function() {
+      expect(binding('phone.name')).toBe('Nexus S');
+    });
+  });
+...
+</pre>
+
+
+You can now rerun `./scripts/e2e-test.sh` or refresh the browser tab with the end-to-end test
+runner to see the tests run, or you can see them running on {@link
+http://angular.github.com/angular-phonecat/step-8/test/e2e/runner.html
+Angular's server}.
+
+
+# Experiments
+
+* Using the {@link guide/dev_guide.e2e-testing Angular's end-to-end test runner API}, write a test
+that verifies that we display 4 thumbnail images on the Nexus S details page.
+
+
+# Summary
+
+Now that the phone details view is in place, proceed to {@link step_09 step 9} to learn how to
+write your own custom display filter.
+
+
+<ul doc-tutorial-nav="8"></ul>
@@ -0,0 +1,141 @@
+@ngdoc overview
+@name Tutorial: 9 - Filters
+@description
+
+<ul doc-tutorial-nav="9"></ul>
+
+
+In this step you will learn how to create your own custom display filter.
+
+
+<div doc-tutorial-reset="9"></div>
+
+
+Navigate to one of the detail pages.
+
+In the previous step, the details page displayed either "true" or "false" to indicate whether
+certain phone features were present or not. We have used a custom filter to convert those text
+strings into glyphs: ✓ for "true", and ✘ for "false". Let's see what the filter code looks like.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-8...step-9
+GitHub}:
+
+
+## Custom Filter
+
+In order to create a new filter, you are going to create a `phonecatFilters` module and register
+your custom filter with this module:
+
+__`app/js/filters.js`:__
+<pre>
+angular.module('phonecatFilters', []).filter('checkmark', function() {
+  return function(input) {
+    return input ? '\u2713' : '\u2718';
+  };
+});
+</pre>
+
+The name of our filter is "checkmark". The `input` evaluates to either `true` or `false`, and we
+return one of the two unicode characters we have chosen to represent true (`\u2713` -> ✓) or false (`\u2718` -> ✘).
+
+Now that our filter is ready, we need to register the `phonecatFilters` module as a dependency for
+our main `phonecat` module.
+
+__`app/js/app.js`:__
+<pre>
+...
+angular.module('phonecat', ['phonecatFilters']).
+...
+</pre>
+
+
+## Template
+
+Since the filter code lives in the `app/js/filters.js` file, we need to include this file in our
+layout template.
+
+__`app/index.html`:__
+<pre>
+...
+ <script src="js/controllers.js"></script>
+ <script src="js/filters.js"></script>
+...
+</pre>
+
+The syntax for using filters in Angular templates is as follows:
+
+    {{ expression | filter }}
+
+Let's employ the filter in the phone details template:
+
+
+
+__`app/partials/phone-detail.html`:__
+<pre>
+...
+    <dl>
+      <dt>Infrared</dt>
+      <dd>{{phone.connectivity.infrared | checkmark}}</dd>
+      <dt>GPS</dt>
+      <dd>{{phone.connectivity.gps | checkmark}}</dd>
+    </dl>
+...
+</pre>
+
+
+## Test
+
+Filters, like any other component, should be tested and these tests are very easy to write.
+
+__`test/unit/filtersSpec.js`:__
+<pre>
+describe('filter', function() {
+
+  beforeEach(module('phonecatFilters'));
+
+  describe('checkmark', function() {
+
+    it('should convert boolean values to unicode checkmark or cross',
+        inject(function(checkmarkFilter) {
+      expect(checkmarkFilter(true)).toBe('\u2713');
+      expect(checkmarkFilter(false)).toBe('\u2718');
+    }));
+  });
+});
+</pre>
+
+We must call `beforeEach(module('phonecatFilters'))` before any of
+our filter tests execute. This call loads our `phonecatFilters` module into the injector
+for this test run.
+
+Note that we call the helper function, `inject(function(checkmarkFilter) { ... })`, to get
+access to the filter that we want to test.  See {@link api/angular.mock.inject angular.mock.inject()}.
+
+You should now see the following output in the Karma tab:
+
+        Chrome 22.0: Executed 4 of 4 SUCCESS (0.034 secs / 0.012 secs)
+
+
+# Experiments
+
+* Let's experiment with some of the {@link api/ng.$filter built-in Angular filters} and add the
+following bindings to `index.html`:
+  * `{{ "lower cap string" | uppercase }}`
+  * `{{ {foo: "bar", baz: 23} | json }}`
+  * `{{ 1304375948024 | date }}`
+  * `{{ 1304375948024 | date:"MM/dd/yyyy @ h:mma" }}`
+
+*  We can also create a model with an input element, and combine it with a filtered binding. Add
+the following to index.html:
+
+        <input ng-model="userInput"> Uppercased: {{ userInput | uppercase }}
+
+
+# Summary
+
+Now that you have learned how to write and test a custom filter, go to {@link step_10 step 10} to
+learn how we can use Angular to enhance the phone details page further.
+
+
+<ul doc-tutorial-nav="9"></ul>
@@ -0,0 +1,141 @@
+@ngdoc overview
+@name Tutorial: 10 - Event Handlers
+@description
+
+<ul doc-tutorial-nav="10"></ul>
+
+
+In this step, you will add a clickable phone image swapper to the phone details page.
+
+
+<div doc-tutorial-reset="10"></div>
+
+
+The phone details view displays one large image of the current phone and several smaller thumbnail
+images. It would be great if we could replace the large image with any of the thumbnails just by
+clicking on the desired thumbnail image. Let's have a look at how we can do this with Angular.
+
+The most important changes are listed below. You can see the full diff on {@link
+https://github.com/angular/angular-phonecat/compare/step-9...step-10
+GitHub}:
+
+
+## Controller
+
+__`app/js/controllers.js`:__
+<pre>
+...
+function PhoneDetailCtrl($scope, $routeParams, $http) {
+  $http.get('phones/' + $routeParams.phoneId + '.json').success(function(data) {
+    $scope.phone = data;
+    $scope.mainImageUrl = data.images[0];
+  });
+
+  $scope.setImage = function(imageUrl) {
+    $scope.mainImageUrl = imageUrl;
+  }
+}
+
+//PhoneDetailCtrl.$inject = ['$scope', '$routeParams', '$http'];
+</pre>
+
+In the `PhoneDetailCtrl` controller, we created the `mainImageUrl` model property and set its
+default value to the first phone image URL.
+
+We also created a `setImage` event handler function that will change the value of `mainImageUrl`.
+
+
+## Template
+
+__`app/partials/phone-detail.html`:__
+<pre>
+<img ng-src="{{mainImageUrl}}" class="phone">
+
+...
+
+<ul class="phone-thumbs">
+  <li ng-repeat="img in phone.images">
+    <img ng-src="{{img}}" ng-click="setImage(img)">
+  </li>
+</ul>
+...
+</pre>
+
+We bound the `ngSrc` directive of the large image to the `mainImageUrl` property.
+
+We also registered an {@link api/ng.directive:ngClick `ngClick`}
+handler with thumbnail images. When a user clicks on one of the thumbnail images, the handler will
+use the `setImage` event handler function to change the value of the `mainImageUrl` property to the
+URL of the thumbnail image.
+
+<div style="display: none">
+TODO!
+<img  class="diagram" src="img/tutorial/tutorial_10-11_final.png">
+</div>
+
+## Test
+
+To verify this new feature, we added two end-to-end tests. One verifies that the main image is set
+to the first phone image by default. The second test clicks on several thumbnail images and
+verifies that the main image changed appropriately.
+
+__`test/e2e/scenarios.js`:__
+<pre>
+...
+  describe('Phone detail view', function() {
+
+...
+
+    it('should display the first phone image as the main phone image', function() {
+      expect(element('img.phone').attr('src')).toBe('img/phones/nexus-s.0.jpg');
+    });
+
+
+    it('should swap main image if a thumbnail image is clicked on', function() {
+      element('.phone-thumbs li:nth-child(3) img').click();
+      expect(element('img.phone').attr('src')).toBe('img/phones/nexus-s.2.jpg');
+
+      element('.phone-thumbs li:nth-child(1) img').click();
+      expect(element('img.phone').attr('src')).toBe('img/phones/nexus-s.0.jpg');
+    });
+  });
+});
+</pre>
+
+You can now rerun `./scripts/e2e-test.sh` or refresh the browser tab with the end-to-end test
+runner to see the tests run, or you can see them running on {@link
+http://angular.github.com/angular-phonecat/step-10/test/e2e/runner.html
+Angular's server}.
+
+# Experiments
+
+* Let's add a new controller method to `PhoneDetailCtrl`:
+
+          $scope.hello = function(name) {
+              alert('Hello ' + (name || 'world') + '!');
+          }
+
+  and add:
+
+          <button ng-click="hello('Elmo')">Hello</button>
+
+  to the `phone-details.html` template.
+
+<div style="display: none">
+TODO!
+  The controller methods are inherited between controllers/scopes, so you can use the same snippet
+in the `phone-list.html` template as well.
+
+* Move the `hello` method from `PhoneCatCtrl` to `PhoneListCtrl` and you'll see that the button
+declared in `index.html` will stop working, while the one declared in the `phone-list.html`
+template remains operational.
+</div>
+
+
+# Summary
+
+With the phone image swapper in place, we're ready for {@link step_11 step 11} (the last step!) to
+learn an even better way to fetch data.
+
+
+<ul doc-tutorial-nav="10"></ul>
--- a/Show More
+++ b/Show More
				`@@ -1 +0,0 @@`
				`org.eclipse.wst.jsdt.launching.JRE_CONTAINER`