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.

1 files changed, 17 insertions, 0 deletions

diff --git a/closure/README.md b/closure/README.md
new file mode 100644
index 00000000..2501a2ad
--- /dev/null
+++ b/closure/README.md
@@ -0,0 +1,17 @@
+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:
+```js
+/** @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/