docs($compile): deprecate replace directives

BREAKING CHANGE:

The `replace` flag for defining directives that
replace the element that they are on will be removed in the next
major angular version.
This feature has difficult semantics (e.g. how attributes are merged)
and leads to more problems compared to what it solves.
Also, with WebComponents it is normal to have custom elements in the DOM.

src/ng/compile.js

@@ -59,7 +59,6 @@
  *       template: '<div></div>', // or // function(tElement, tAttrs) { ... },
  *       // or
  *       // templateUrl: 'directive.html', // or // function(tElement, tAttrs) { ... },
- *       replace: false,
  *       transclude: false,
  *       restrict: 'A',
  *       scope: false,
@@ -248,7 +247,7 @@
  * api/ng.$sce#getTrustedResourceUrl $sce.getTrustedResourceUrl}.
  *
  *
- * #### `replace`
+ * #### `replace` ([*DEPRECATED*!], will be removed in next major release)
  * specify where the template should be inserted. Defaults to `false`.
  *
  * * `true` - the template will replace the current element.