docs

Author: olov

IMPLICIT.md

@@ -0,0 +1,98 @@
+# Implicit matching
+ng-annotate uses static analysis to detect common AngularJS code patterns. 
+There are patterns it does not and never will understand and for those you
+should use `"ngInject"` instead, see [README.md](README.md).
+
+
+## Declaration forms
+ng-annotate understands the two common declaration forms:
+
+Long form:
+
+```js
+angular.module("MyMod").controller("MyCtrl", function($scope, $timeout) {
+});
+```
+
+Short form:
+
+```js
+myMod.controller("MyCtrl", function($scope, $timeout) {
+});
+```
+
+It's not limited to `.controller` of course. It understands `.config`, `.factory`,
+`.directive`, `.filter`, `.run`, `.controller`, `.provider`, `.service`, `.decorator`,
+`.component`, `.animation` and `.invoke`.
+
+For short forms it does not need to see the declaration of `myMod` so you can run it
+on your individual source files without concatenating. If ng-annotate detects a short form
+false positive then you can use the `--regexp` option to limit the module identifier.
+Examples: `--regexp "^myMod$"` (match only `myMod`) or `--regexp "^$"` (ignore short forms).
+You can also use `--regexp` to opt-in for more advanced method callee matching, for
+example `--regexp "^require(.*)$"` to detect and transform
+`require('app-module').controller(..)`. Not using the option is the same as passing
+`--regexp "^[a-zA-Z0-9_\$\.\s]+$"`, which means that the callee can be a (non-unicode)
+identifier (`foo`), possibly with dot notation (`foo.bar`).
+
+ng-annotate understands `angular.module("MyMod", function(dep) ..)` as an alternative to
+`angular.module("MyMod").config(function(dep) ..)`.
+
+ng-annotate understands `this.$get = function($scope) ..` and
+`{.., $get: function($scope) ..}` inside a `provider`. `self` and `that` can be used as
+aliases for `this`.
+
+ng-annotate understands `return {.., controller: function($scope) ..}` inside a
+`directive`.
+
+ng-annotate understands `$provide.decorator("bar", function($scope) ..)`, `$provide.service`,
+`$provide.factory` and `$provide.provider`.
+
+ng-annotate understands `$routeProvider.when("path", { .. })`.
+
+ng-annotate understands `$controllerProvider.register("foo", function($scope) ..)`.
+
+ng-annotate understands `$httpProvider.interceptors.push(function($scope) ..)` and
+`$httpProvider.responseInterceptors.push(function($scope) ..)`.
+
+ng-annotate understands `$injector.invoke(function ..)`.
+
+ng-annotate understands [ui-router](https://github.com/angular-ui/ui-router) (`$stateProvider` and
+`$urlRouterProvider`).
+
+ng-annotate understands `$uibModal.open` (and `$modal.open`) ([angular-ui/bootstrap](http://angular-ui.github.io/bootstrap/)).
+
+ng-annotate understands `$mdDialog.show`, `$mdToast.show` and `$mdBottomSheet.show`
+([angular material design](https://material.angularjs.org/#/api/material.components.dialog/service/$mdDialog)).
+
+ng-annotate understands `myMod.store("MyCtrl", function ..)`
+([flux-angular](https://github.com/christianalfoni/flux-angular)).
+
+ng-annotate understands chaining.
+
+ng-annotate understands IIFE's and attempts to match through them, so
+`(function() { return function($scope) .. })()` works anywhere
+`function($scope) ..` does (for any IIFE args and params).
+
+ng-annotate understands [angular-dashboard-framework](https://github.com/sdorra/angular-dashboard-framework)
+via optional `--enable angular-dashboard-framework`.
+
+
+## Reference-following
+ng-annotate follows references. This works if and only if the referenced declaration is
+a) a function declaration or
+b) a variable declaration with an initializer.
+Modifications to a reference outside of its declaration site are ignored by ng-annotate.
+
+These examples will get annotated:
+
+```js
+function MyCtrl($scope, $timeout) {
+}
+var MyCtrl2 = function($scope) {};
+
+angular.module("MyMod").controller("MyCtrl", MyCtrl);
+angular.module("MyMod").controller("MyCtrl", MyCtrl2);
+```
+
+

OPTIONS.md

@@ -0,0 +1,54 @@
+## ng-annotate command-line options
+
+`ng-annotate OPTIONS <file>`. The errors (if any) will go to stderr,
+the transpiled output to stdout.
+
+Use the `--add` (`-a`) option to add annotations where non-existing,
+use `--remove` (`-r`) to remove all existing annotations,
+use `--add --remove` (`-ar`) to rebuild all annotations.
+
+Use the `-o` option to write output to file.
+
+Provide `-` instead of an input `<file>` to read input from stdin.
+
+Use the `--sourcemap` option to generate an inline sourcemap.
+
+Use the `--sourceroot` option to set the sourceRoot property of the generated sourcemap.
+
+Use the `--single_quotes` option to output `'$scope'` instead of `"$scope"`.
+
+Use the `--regexp` option to restrict matching further or to expand matching.
+See description further down.
+
+Use the `--list` option to list optional matchers.
+
+Use the `--enable` option to enable optional matcher.
+
+*experimental* Use the `--rename` option to rename providers (services, factories,
+controllers, etc.) with a new name when declared and referenced through annotation.
+Use it like this: `--rename oldname1 newname1 oldname2 newname2`
+
+*experimental* Use the `--plugin` option to load a user plugin with the provided path,
+1.x may change API). See [plugin-example.js](plugin-example.js) for more info.
+
+*experimental* Use the `--stats` option to print statistics on stderr.
+
+
+## Library (API)
+ng-annotate can be used as a library. See [ng-annotate.js](ng-annotate.js) for further info about
+options and return value.
+
+```js
+var ngAnnotate = require("ng-annotate");
+var somePlugin = require("./some/path/some-plugin");
+var res = ngAnnotate(src, {
+    add: true,
+    plugin: [somePlugin],
+    rename: [{from: "generalname", to: "uniquename"}, {from: "alpha", to: "beta"}],
+    map: { inline: false, inFile: "source.js", sourceRoot: "/path/to/source/root" },
+    enable: ["angular-dashboard-framework"],
+});
+var errorstringArray = res.errors;
+var transformedSource = res.src;
+var transformedSourceMap = res.map;
+```