chore(docs): deprecation notices for methods and properties

docs/app/assets/css/docs.css

@@ -662,6 +662,11 @@ ul.events > li {
   max-width: 100%;
 }
 
+.deprecation .title {
+  float: left;
+  margin-right: 5px;
+}
+
 @media only screen and (min-width: 769px) {
   [ng-include="partialPath"].ng-hide {
     display: block !important;

docs/config/index.js

@@ -52,10 +52,12 @@ module.exports = new Package('angularjs', [
 
 
 .config(function(parseTagsProcessor) {
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/deprecated')); // this will override the jsdoc version
   parseTagsProcessor.tagDefinitions.push(require('./tag-defs/tutorial-step'));
   parseTagsProcessor.tagDefinitions.push(require('./tag-defs/sortOrder'));
   parseTagsProcessor.tagDefinitions.push(require('./tag-defs/installation'));
   parseTagsProcessor.tagDefinitions.push(require('./tag-defs/this'));
+
 })
 
 
@@ -65,7 +67,11 @@ module.exports = new Package('angularjs', [
 
 
 .config(function(templateFinder, renderDocsProcessor, gitData) {
-  templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates'));
+  // We are completely overwriting the folders
+  templateFinder.templateFolders.length = 0;
+  templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/examples'));
+  templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/ngdoc'));
+  templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/app'));
   renderDocsProcessor.extraData.git = gitData;
 })
 

docs/config/tag-defs/deprecated.js

@@ -0,0 +1,42 @@
+'use strict';
+
+var OPTION_MATCHER = /^\s*([\w-]+)="([^"]+)"\s+([\s\S]*)/;
+var VALID_OPTIONS = ['sinceVersion', 'removeVersion'];
+
+module.exports = {
+  name: 'deprecated',
+  transforms: function(doc, tag, value) {
+    var result = {};
+    var invalidOptions = [];
+    value = value.trim();
+    while (OPTION_MATCHER.test(value)) {
+      value = value.replace(OPTION_MATCHER, function(_, key, value, rest) {
+        if (VALID_OPTIONS.indexOf(key) !== -1) {
+          result[key] = value;
+        } else {
+          invalidOptions.push(key);
+        }
+        return rest;
+      });
+    }
+    if (invalidOptions.length > 0) {
+      throw new Error('Invalid options: ' + humanList(invalidOptions) + '. Value options are: ' + humanList(VALID_OPTIONS));
+    }
+    result.description = value;
+    return result;
+  }
+};
+
+function humanList(values, sep, lastSep) {
+  if (sep === undefined) sep = ', ';
+  if (lastSep === undefined) lastSep = ' and ';
+
+  return values.reduce(function(output, value, index, list) {
+    output += '"' + value + '"';
+    switch (list.length - index) {
+      case 1: return output;
+      case 2: return output + lastSep;
+      default: return output + sep;
+    }
+  }, '');
+}

docs/config/tag-defs/deprecated.spec.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/* globals describe, it, expect */
+var tagDef = require('./deprecated');
+
+describe('deprecated tag', function() {
+  describe('transforms', function() {
+    it('should return the trimmed value if no options', function() {
+      var tag = tagDef.transforms({}, {}, 'This is the description');
+      expect(tag.description).toEqual('This is the description');
+    });
+
+    it('should read options', function() {
+      var tag = tagDef.transforms({}, {}, ' sinceVersion="v1.3.4" removeVersion="v1.4.5" what is left is description');
+      expect(tag.description).toEqual('what is left is description');
+      expect(tag.sinceVersion).toEqual('v1.3.4');
+      expect(tag.removeVersion).toEqual('v1.4.5');
+    });
+
+    it('should cope with carriage returns', function() {
+      var tag = tagDef.transforms({}, {}, '\nsinceVersion="v1.3.4"\nremoveVersion="v1.4.5"\nwhat is left is description');
+      expect(tag.description).toEqual('what is left is description');
+      expect(tag.sinceVersion).toEqual('v1.3.4');
+      expect(tag.removeVersion).toEqual('v1.4.5');
+    });
+
+    it('should error if there is an invalid option', function() {
+      expect(function() {
+        tagDef.transforms({}, {}, ' fromVersion="v1.3.4" toVersion="v1.4.5" what is left is description');
+      }).toThrowError('Invalid options: "fromVersion" and "toVersion". Value options are: "sinceVersion" and "removeVersion"');
+    });
+  });
+});

docs/config/templates/examples/index.template.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en"{% if doc.example['ng-csp'] %} ng-csp{% endif %}>
+<head>
+  <meta charset="UTF-8">
+  <title>Example - {$ doc.id $}</title>
+  {% for stylesheet in doc.stylesheets %}<link href="{$ stylesheet.path $}" rel="stylesheet" type="text/css">
+  {% endfor %}
+
+  {% for script in doc.scripts %}<script src="{$ script.path $}"></script>
+  {% endfor %}
+
+  {% if doc.example.fixBase -%}
+  <script type="text/javascript">
+    angular.element(document.getElementsByTagName('head')).append(angular.element('<base href="' + window.location.pathname + '" />'));
+  </script>
+  {%- endif %}
+</head>
+<body {% if not doc.example['ng-app-included'] %}ng-app="{$ doc.example.module $}"{% endif %}>
+  {$ doc.fileContents $}
+</body>
+</html>

docs/config/templates/examples/manifest.template.json

@@ -0,0 +1,8 @@
+{
+  "name": "{$ doc.example.id $}",
+  "files": [
+    "index-production.html"
+    {%- for file in doc.files %},
+    "{$ file $}"{% endfor %}
+  ]
+}

docs/config/templates/examples/protractorTests.template.js

@@ -0,0 +1,10 @@
+describe("{$ doc.description $}", function() {
+  var rootEl;
+  beforeEach(function() {
+    rootEl = browser.rootEl;{% if doc['ng-app-included'] %}
+    browser.rootEl = '[ng-app]';{% endif %}
+    browser.get("{$ doc.basePath $}{$ doc.example.deployments[doc.deployment.name].outputPath $}");
+  });
+  {% if doc['ng-app-included'] %}afterEach(function() { browser.rootEl = rootEl; });{% endif %}
+{$ doc.innerTest $}
+});

docs/config/templates/examples/template.css

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/examples/template.html

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/examples/template.js

@@ -0,0 +1,4 @@
+(function(angular) {
+  'use strict';
+{$ doc.fileContents $}
+})(window.angular);

docs/config/templates/examples/template.json

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/examples/template.protractor

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/examples/template.scenario

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/examples/template.spec

@@ -0,0 +1 @@
+{$ doc.fileContents $}

docs/config/templates/api/api.template.html → docs/config/templates/ngdoc/api/api.template.html

@@ -1,4 +1,5 @@
 {% extends "base.template.html" %}
+{% import "lib/deprecated.html" as x -%}
 
 {% block content %}
 
@@ -18,6 +19,8 @@ <h1 class="api-profile-header-heading">{$ doc.name $}</h1>
 </header>
 {% endblock %}
 
+{$ x.deprecatedBlock(doc) $}
+
 {% block description %}
 <div class="api-profile-description">
   {$ doc.description | marked $}
@@ -28,18 +31,11 @@ <h1 class="api-profile-header-heading">{$ doc.name $}</h1>
 <h2 id="known-issues">Known Issues</h2>
 {% for issue in doc.knownIssues -%}
 <div class="known-issue">
-  {$ issue | marked $}  {% if not loop.last %}<hr>{% endif %}
+  {$ issue | marked $}
 </div>
 {% endfor -%}
 {% endif %}
 
-{% if doc.deprecated %}
-<fieldset class="deprecated">
-  <legend>Deprecated API</legend>
-  {$ doc.deprecated| marked $}
-</fieldset>
-{% endif %}
-
 <div>
   {% block dependencies %}
   {%- if doc.requires %}

docs/config/templates/ngdoc/api/componentGroup.template.html

@@ -0,0 +1,31 @@
+{% block content %}
+<h1>
+  {%- if doc.title -%}
+    {$ doc.title $}
+  {%- elif doc.moduleName -%}
+    {$ doc.groupType | title $} components in {$ doc.moduleName | code $}
+  {%- else -%}
+    Pages
+  {%- endif -%}
+</h1>
+
+{$ doc.description | marked $}
+
+<div class="component-breakdown">
+  <div>
+    <table class="definition-table">
+      <tr>
+        <th>Name</th>
+        <th>Description</th>
+      </tr>
+      {% for page in doc.components %}
+      <tr>
+        <td>{$ page.id | link(page.name, page) $}</td>
+        <td>{$ page.description | firstParagraph | marked $}</td>
+      </tr>
+      {% endfor %}
+    </table>
+  </div>
+</div>
+
+{% endblock %}

docs/config/templates/ngdoc/api/directive.template.html

@@ -0,0 +1,72 @@
+{% import "lib/macros.html" as lib -%}
+{% extends "api/api.template.html" %}
+
+{% block additional %}
+  <h2>Directive Info</h2>
+  <ul>
+    {% if doc.scope %}<li>This directive creates new scope.</li>{% endif %}
+    <li>This directive executes at priority level {$ doc.priority $}.</li>
+    {% if doc.multiElement %}<li>This directive can be used as {@link $compile#-multielement- multiElement}</li>{% endif %}
+  </ul>
+
+  {% block usage %}
+  <h2 id="usage">Usage</h2>
+  <div class="usage">
+  {% if doc.usage %}
+    {$ doc.usage | marked $}
+  {% else %}
+    <ul>
+    {% if doc.restrict.element %}
+      <li>as element:
+      {% if doc.name.indexOf('ng') == 0 -%}
+      (This directive can be used as custom element, but be aware of <a href="guide/ie">IE restrictions</a>).
+      {%- endif %}
+      {% code %}
+      <{$ doc.name | dashCase $}
+        {%- for param in doc.params %}
+        {$ lib.directiveParam(param.alias or param.name, param.type, '="', '"') $}
+        {%- endfor %}>
+      ...
+      </{$ doc.name | dashCase $}>
+      {% endcode %}
+      </li>
+    {% endif -%}
+
+    {%- if doc.restrict.attribute -%}
+      <li>as attribute:
+        {% code %}
+        <{$ doc.element $}
+          {%- for param in doc.params %}
+          {$ lib.directiveParam(param.name, param.type, '="', '"') $}
+          {%- endfor %}>
+        ...
+        </{$ doc.element $}>
+        {% endcode %}
+      </li>
+    {% endif -%}
+
+    {%- if doc.restrict.cssClass -%}
+      <li>as CSS class:
+        {% code %}
+        {% set sep = joiner(' ') %}
+        <{$ doc.element $} class="
+        {%- for param in doc.params -%}
+          {$ sep() $}{$ lib.directiveParam(param.name, param.type, ': ', ';') $}
+        {%- endfor %}"> ... </{$ doc.element $}>
+        {% endcode %}
+      </li>
+    {% endif -%}
+
+  {%- endif %}
+  </div>
+  {% endblock -%}
+
+  {%- if doc.animations %}
+  <h2 id="animations">Animations</h2>
+  {$ doc.animations | marked $}
+  {$ 'module:ngAnimate.$animate' | link('Click here', doc) $} to learn more about the steps involved in the animation.
+  {%- endif -%}
+
+  {% include "lib/params.template.html" %}
+  {% include "lib/events.template.html" %}
+{% endblock %}

docs/config/templates/ngdoc/api/filter.template.html

@@ -0,0 +1,26 @@
+{% import "lib/macros.html" as lib -%}
+{% extends "api/api.template.html" %}
+
+{% block additional %}
+  <h2>Usage</h2>
+  <h3>In HTML Template Binding</h3>
+  {% if doc.usage %}
+    {$ doc.usage | code $}
+  {% else %}
+    {% code -%}
+    {{ {$ doc.name $}_expression | {$ doc.name $}
+      {%- for param in doc.params %}{% if not loop.first %} : {$ param.name $}{% endif %}{% endfor -%}
+    }}
+    {%- endcode %}
+  {% endif %}
+
+  <h3>In JavaScript</h3>
+  {% code -%}
+    {%- set sep = joiner(', ') -%}
+    $filter('{$ doc.name $}')({% for param in doc.params %}{$ sep() $}{$ param.name $}{% endfor -%})
+  {%- endcode %}
+
+  {% include "lib/params.template.html" %}
+  {% include "lib/this.template.html" %}
+  {% include "lib/returns.template.html" %}
+{% endblock %}

docs/config/templates/ngdoc/api/function.template.html

@@ -0,0 +1 @@
+{% extends "api/object.template.html" %}

docs/config/templates/ngdoc/api/input.template.html

@@ -0,0 +1,12 @@
+{% import "lib/macros.html" as lib -%}
+{% extends "api/directive.template.html" %}
+
+{% block usage %}
+  <h2>Usage</h2>
+  {% code %}
+  <input type="{$ doc.inputType $}"
+    {%- for param in doc.params %}
+         {$ lib.directiveParam(param.alias or param.name, param.type, '="', '"') $}
+    {%- endfor %}>
+  {% endcode %}
+{% endblock %}

docs/config/templates/api/module.template.html → docs/config/templates/ngdoc/api/module.template.html

@@ -1,10 +1,13 @@
 {% extends "base.template.html" %}
+{% import "lib/deprecated.html" as x %}
 
 {% block content %}
 <h1>
   {% if doc.title %}{$ doc.title | marked $}{% else %}{$ doc.name | code $}{% endif %}
 </h1>
 
+{$ x.deprecatedBlock(doc) $}
+
 <h2>Installation</h2>
 {% if doc.installation or doc.installation == '' %}
   {$ doc.installation | marked $}