3 files changed, 83 insertions, 0 deletions
diff --git a/docs/angular.attrMarkup.ngdoc b/docs/angular.attrMarkup.ngdoc
new file mode 100644
index 00000000..f73a5b42
--- /dev/null
+++ b/docs/angular.attrMarkup.ngdoc
@@ -0,0 +1,15 @@
+@workInProgress
+@ngdoc overview
+@name angular.attrMarkup
+
+@description
+Attribute markup extends the angular compiler in a very similar way as {@link angular.markup} except
+that it allows you to modify the state of the attribute text rather then the contest of a node.
+
+<pre>
+angular.attrMarkup('extraClass', function(attrValue, attrName, element){
+  if (attrName == 'additional-class') {
+    element.addClass(attrValue);
+  }
+});
+</pre>
diff --git a/docs/angular.markup.ngdoc b/docs/angular.markup.ngdoc
new file mode 100644
index 00000000..a40385c8
--- /dev/null
+++ b/docs/angular.markup.ngdoc
@@ -0,0 +1,66 @@
+@workInProgress
+@ngdoc overview
+@name angular.markup
+
+@description
+#Overview
+Markups allow the angular compiler to transform content of DOM elements or portions of this content
+into other text or DOM elements for further compilation. Markup extensions do not themselves produce
+linking functions. Think of markup as a way to produce shorthand for a {@link angular.widget widget}
+ or a {@link angular.directive directive}.
+
+#`{{}}` (double curly) built-in markup
+`{{}}` markup is a built-in markup, which translates the enclosed expression into an
+{@link angular.directive.ng:bind ng:bind} directive. It simply transforms
+
+<pre>
+{{expression}}
+</pre>
+
+to:
+
+<pre>
+<span ng:bind="expression"></span>
+</pre>
+
+For example `{{1+2}}` is easier to write and understand than `<span ng:bind="1+2"></span>`. The
+expanded elements are then {@link guide.compiler compiled} normally.
+
+# Custom markup
+Let's say you want to define this shorthand for a horizontal rule: `---` for `<hr/>`.
+
+In other words, this HTML:
+<pre>
+header
+---
+footer
+</pre>
+
+should translate to:
+<pre>
+header
+<hr/>
+footer
+</pre>
+
+Here's how the angular compiler could be extended to achieve this:
+<pre>
+angular.markup('---', function(text, textNode, parentElement) {
+  var compiler = this;
+  var index = text.indexOf('---');
+  if (index > -1) {
+    var before = compiler.text(text.substring(0, index));
+    var hr = compiler.element('hr');
+    var after = compiler.text(text.substring(index + 3));
+    textNode.after(after);
+    textNode.after(hr);
+    textNode.after(before);
+    textNode.remove();
+  }
+});
+</pre>
+
+Unlike {@link angular.widget widgets} and {@link angular.directive directives}, in which the
+compiler matches the name of handler function to a DOM element or attribute name, for markup the
+compiler calls every markup handler for every text node, giving the handler a chance to transform
+the text. The markup handler needs to find all the matches in the text.
diff --git a/src/Angular.js b/src/Angular.js
index aea1dd3f..710d96f5 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -94,7 +94,9 @@ var _undefined        = undefined,
 
     /** @name angular */
     angular           = window[$angular]    || (window[$angular] = {}),
+    /** @name angular.markup */
     angularTextMarkup = extensionMap(angular, 'markup'),
+    /** @name angular.attrMarkup */
     angularAttrMarkup = extensionMap(angular, 'attrMarkup'),
     /** @name angular.directive */
     angularDirective  = extensionMap(angular, 'directive'),