# `annotate` ( service in module `AUTO` )

## Description

Returns an array of service names which the function is requesting for injection. This API is used by the injector to determine which services need to be injected into the function when the function is invoked. There are three ways in which the function can be annotated with the needed dependencies.

# Argument names

The simplest form is to extract the dependencies from the arguments of the function. This is done by converting the function into a string using `toString()` method and extracting the argument names.

      // Given
      function MyController($scope, $route) {
        // ...
      }

      // Then
      expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);

This method does not work with code minfication / obfuscation. For this reason the following annotation strategies are supported.

# The `$inject` property

If a function has an `$inject` property and its value is an array of strings, then the strings represent names of services to be injected into the function.

      // Given
      var MyController = function(obfuscatedScope, obfuscatedRoute) {
        // ...
      }
      // Define function dependencies
      MyController.$inject = ['$scope', '$route'];

      // Then
      expect(injector.annotate(MyController)).toEqual(['$scope', '$route']);

# The array notation

It is often desirable to inline Injected functions and that's when setting the `$inject` property is very inconvenient. In these situations using the array notation to specify the dependencies in a way that survives minification is a better choice:

      // We wish to write this (not minification / obfuscation safe)
      injector.invoke(function($compile, $rootScope) {
        // ...
      });

      // We are forced to write break inlining
      var tmpFn = function(obfuscatedCompile, obfuscatedRootScope) {
        // ...
      };
      tmpFn.$inject = ['$compile', '$rootScope'];
      injector.invoke(tmpFn);

      // To better support inline function the inline annotation is supported
      injector.invoke(['$compile', '$rootScope', function(obfCompile, obfRootScope) {
        // ...
      }]);

      // Therefore
      expect(injector.annotate(
         ['$compile', '$rootScope', function(obfus_$compile, obfus_$rootScope) {}])
       ).toEqual(['$compile', '$rootScope']);

## Parameters

- `fn – {function|Array.<string|Function>} –`

  Function for which dependent service names need to be retrieved as described above.

## Returns

`{Array.<string>}` –

The names of the services which the function requires.