1 files changed, 59 insertions, 0 deletions
diff --git a/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc b/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc
new file mode 100644
index 00000000..53da202c
--- /dev/null
+++ b/docs/content/guide/dev_guide.compiler.directives_widgets.ngdoc
@@ -0,0 +1,59 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Angular HTML Compiler: Comparing Directives and Attribute Widgets
+@description
+
+
+Although directives and {@link dev_guide.compiler.widgets attribute widgets} appear the same in a
+template (`ng:init` is a directive, `ng:repeat` is an attribute widget), there is a difference in
+the order in which they are evaluated.  The user of existing directives or widgets cannot determine
+the order of evaluation. The evaluation order is the responsibility of the developer creating
+custom directives and widgets.
+
+
+For example, consider this piece of HTML, which uses the `ng:repeat`, `ng:init`, and `ng:bind`
+widget and directives:
+
+
+<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. Because we want to run the `ng:init="a=a+1` and
+`ng:bind="person"` once for each `person in people`, we need to execute {@link
+api/angular.widget.@ng:repeat ng:repeat} to make copies of the `<li>` element before we run the
+{@link api/angular.directive.ng:init ng:init}, and {@link api/angular.directive.ng:bind ng:bind}
+for each of the `<li>`copies.
+
+
+If you implemented `ng:repeat` as a directive, there would be no guarantee that the attributes
+`ng:repeat`, `ng:init`, and `ng:bind` would be evaluated in the order they are declared, because
+the order of element attributes in HTML is not significant to the browser.
+
+
+So, when creating a custom HTML attribute, you will have to consider whether a directive or a
+widget is more appropriate. When the order of execution doesn't matter, directives are the right
+choice. In a situation where the order matters and one attribute should be processed with a higher
+priority than others, use a widget for the attribute that must be processed first.
+
+
+
+
+## Related Topics
+
+
+* {@link dev_guide.compiler.directives Understanding Angular Directives}
+* {@link dev_guide.compiler.widgets Understanding Angular Widgets}
+
+
+## Related API:
+
+
+* {@link api/angular.directive Directive API}
+* {@link api/angular.widget Widget API}