@workInProgress
@ngdoc overview
@name angular.directive
@namespace Namespace for all directives.

@description
A directive is an HTML attribute that you can use in an existing HTML element type or in a
DOM element type that you create as {@link angular.widget}, to modify that element's
properties. You can use any number of directives per element.

For example, you can add the ng:bind directive as an attribute of an HTML span element, as in
`<span ng:bind="1+2"></span>`. How does this work? The compiler passes the attribute value
`1+2` to the ng:bind extension, which in turn tells the {@link angular.scope} to watch that
expression and report changes. On any change it sets the span text to the expression value.

Here's how to define {@link angular.directive.ng:bind ng:bind}:
<pre>
  angular.directive('ng:bind', function(expression, compiledElement) {
    var compiler = this;
    return function(linkElement) {
      var currentScope = this;
      currentScope.$watch(expression, function(value) {
        linkElement.text(value);
      });
    };
  });
</pre>

# Directive vs. Attribute Widget
Both [attribute widgets](#!angular.widget) and directives can compile a DOM element
attribute. So why have two different ways to do the same thing? The answer is that order
matters, but we have no control over the order in which attributes are read. To solve this
we apply attribute widget before the directive.

For example, consider this piece of HTML, which uses the directives `ng:repeat`, `ng:init`,
and `ng:bind`:
<pre>
  <ul ng:init="people=['mike', 'mary']">
    <li ng:repeat="person in people" ng:init="a=a+1" ng:bind="person"></li>
  </ul>
</pre>

Notice that the order of execution matters here. We need to execute
{@link angular.directive.ng:repeat ng:repeat} before we run the
{@link angular.directive.ng:init ng:init} and `ng:bind` on the `<li/>;`. This is because we
want to run the `ng:init="a=a+1` and `ng:bind="person"` once for each person in people. We
could not have used directive to create this template because attributes are read in an
unspecified order and there is no way of guaranteeing that the repeater attribute would
execute first. Using the `ng:repeat` attribute directive ensures that we can transform the
DOM element into a template.

Widgets run before directives. Widgets may manipulate the DOM whereas directives are not
expected to do so, and so they run last.