chore(docs): deprecation notices for methods and properties

Closes #15351
Closes #15394

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'));
+
 })
 
 
@@ -69,7 +71,6 @@ module.exports = new Package('angularjs', [
   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/git'));
   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/app/runnableExample.template.html

@@ -1,26 +0,0 @@
-{# Be aware that we need these extra new lines here or marked will not realize that the <div>
-   is HTML and wrap each line in a <p> - thus breaking the HTML #}
-
-<div>
-  <plnkr-opener example-path="{$ doc.path $}"></plnkr-opener>
-
-  <div class="runnable-example"
-      path="{$ doc.example.deployments.default.path $}"
-      {%- for attrName, attrValue in doc.example.attributes %}
-      {$ attrName $}="{$ attrValue $}"{% endfor %}>
-
-  {% for fileName, file in doc.example.files %}
-    <div class="runnable-example-file" {% for attrName, attrValue in file.attributes %}
-      {$ attrName $}="{$ attrValue $}"{% endfor %}>
-      {% code -%}
-      {$ file.fileContents $}
-      {%- endcode %}
-    </div>
-  {% endfor %}
-
-    <iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
-  </div>
-</div>
-
-{# Be aware that we need these extra new lines here or marked will not realize that the <div>
-   above is HTML and wrap each line in a <p> - thus breaking the HTML #}

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

@@ -1,24 +1,26 @@
-{# Be aware that we need these extra new lines here or marked will not realise that the <div>
+{# Be aware that we need these extra new lines here or marked will not realize that the <div>
    is HTML and wrap each line in a <p> - thus breaking the HTML #}
 
+<div>
+  <plnkr-opener example-path="{$ doc.path $}"></plnkr-opener>
 
-<div class="runnable-example"
-    path="{$ doc.example.deployments.default.path $}"
-    {%- for attrName, attrValue in doc.example.attributes %}
-    {$ attrName $}="{$ attrValue $}"{% endfor %}>
+  <div class="runnable-example"
+      path="{$ doc.example.deployments.default.path $}"
+      {%- for attrName, attrValue in doc.example.attributes %}
+      {$ attrName $}="{$ attrValue $}"{% endfor %}>
 
- {% for fileName, file in doc.example.files %}
-  <div class="runnable-example-file" {% for attrName, attrValue in file.attributes %}
-    {$ attrName $}="{$ attrValue $}"{% endfor %}>
-    {% code -%}
-    {$ file.fileContents $}
-    {%- endcode %}
+  {% for fileName, file in doc.example.files %}
+    <div class="runnable-example-file" {% for attrName, attrValue in file.attributes %}
+      {$ attrName $}="{$ attrValue $}"{% endfor %}>
+      {% code -%}
+      {$ file.fileContents $}
+      {%- endcode %}
+    </div>
+  {% endfor %}
+
+    <iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
   </div>
-{% endfor %}
-
-  <iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
 </div>
 
-
-{# Be aware that we need these extra new lines here or marked will not realise that the <div>
-   above is HTML and wrap each line in a <p> - thus breaking the HTML #}
+{# Be aware that we need these extra new lines here or marked will not realize that the <div>
+   above is HTML and wrap each line in a <p> - thus breaking the HTML #}

docs/config/templates/git/api/api.template.html

@@ -1,66 +0,0 @@
-{% extends "base.template.html" %}
-
-{% block content %}
-
-<a href='https://github.com/{$ git.info.owner $}/{$ git.info.repo $}/tree/{$ git.version.isSnapshot and 'master' or git.version.raw $}/{$ doc.fileInfo.projectRelativePath $}#L{$ doc.startingLine $}' class='view-source pull-right btn btn-primary'>
-  <i class="glyphicon glyphicon-zoom-in">&nbsp;</i>View Source
-</a>
-
-{% block header %}
-<header class="api-profile-header">
-  <h1 class="api-profile-header-heading">{$ doc.name $}</h1>
-  <ol class="api-profile-header-structure naked-list step-list">
-    {% block related_components %}{% endblock %}
-    <li>
-      - {$ doc.docType $} in module <a href="{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.name $}</a>
-    </li>
-  </ol>
-</header>
-{% endblock %}
-
-{% block description %}
-<div class="api-profile-description">
-  {$ doc.description | marked $}
-</div>
-{% endblock %}
-
-{% if doc.knownIssues %}
-<h2 id="known-issues">Known Issues</h2>
-{% for issue in doc.knownIssues -%}
-<div class="known-issue">
-  {$ 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 %}
-  <h2 id="dependencies">Dependencies</h2>
-  <ul>
-    {% for require in doc.requires %}<li>{$ require | link $}</li>{% endfor %}
-  </ul>
-  {% endif -%}
-  {% endblock %}
-
-  {% block additional %}
-  {% endblock %}
-
-  {% block examples %}
-  {%- if doc.examples %}
-  <h2 id="example">Example</h2>
-  {%- for example in doc.examples -%}
-    {$ example | marked $}
-  {%- endfor -%}
-  {% endif -%}
-  {% endblock %}
-</div>
-
-{% endblock %}

docs/config/templates/git/base.template.html

@@ -1,4 +0,0 @@
-<a href='https://github.com/angular/angular.js/edit/{$ git.version.branch $}/{$ doc.fileInfo.projectRelativePath $}?message=docs({$ (doc.area != "api") and (doc.area + "%2F") or "" $}{$ doc.name $})%3A%20describe%20your%20change...{$ (doc.area == "api") and ("#L" + doc.startingLine) or "" $}' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this Doc</a>
-
-{% block content %}
-{% endblock %}

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

@@ -1,19 +1,26 @@
 {% extends "base.template.html" %}
+{% import "lib/deprecated.html" as x -%}
 
 {% block content %}
 
+<a href='https://github.com/{$ git.info.owner $}/{$ git.info.repo $}/tree/{$ git.version.isSnapshot and 'master' or git.version.raw $}/{$ doc.fileInfo.projectRelativePath $}#L{$ doc.startingLine $}' class='view-source pull-right btn btn-primary'>
+  <i class="glyphicon glyphicon-zoom-in">&nbsp;</i>View Source
+</a>
+
 {% block header %}
 <header class="api-profile-header">
   <h1 class="api-profile-header-heading">{$ doc.name $}</h1>
   <ol class="api-profile-header-structure naked-list step-list">
     {% block related_components %}{% endblock %}
     <li>
-      - {$ doc.docType $} in module {$ doc.moduleDoc.id | link(doc.moduleDoc.name, doc.moduleDoc) $}
+      - {$ doc.docType $} in module <a href="{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.name $}</a>
     </li>
   </ol>
 </header>
 {% endblock %}
 
+{$ x.deprecatedBlock(doc) $}
+
 {% block description %}
 <div class="api-profile-description">
   {$ doc.description | marked $}
@@ -29,13 +36,6 @@
 {% 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/module.template.html

@@ -1,37 +1,48 @@
 {% 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>
 
-{% if doc.name != 'ng' and doc.name != 'auto' %}
-  <h2>Installation</h2>
+{$ x.deprecatedBlock(doc) $}
 
-  <p>First include {$ doc.packageFile | code $} in your HTML:</p>
+<h2>Installation</h2>
+{% if doc.installation or doc.installation == '' %}
+  {$ doc.installation | marked $}
+{% else %}
 
-  {% code %}
-      <script src="angular.js">
-      <script src="{$ doc.packageFile $}">
-  {% endcode %}
-
-  <p>You can download this file from the following places:</p>
+  <p>First, get the file:</p>
   <ul>
     <li>
-      <a href="https://developers.google.com/speed/libraries/devguide#angularjs">Google CDN</a><br>
-      e.g. {$ ("//ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/" + doc.packageFile) | code $}
+      <a href="https://developers.google.com/speed/libraries/devguide#angularjs">Google CDN</a> e.g.
+      {% code %}"//ajax.googleapis.com/ajax/libs/angularjs/X.Y.Z/{$ doc.packageFile $}"{% endcode %}
     </li>
     <li>
-      <a href="http://bower.io">Bower</a><br>
-      e.g. {% code %}bower install {$ doc.packageName $}@X.Y.Z{% endcode %}
+      <a href="https://www.npmjs.com/">NPM</a> e.g.
+      {% code %}npm install {$ doc.packageName $}@X.Y.Z{% endcode %}
     </li>
     <li>
-      <a href="http://code.angularjs.org/">code.angularjs.org</a><br>
-      e.g. {% code %}"//code.angularjs.org/X.Y.Z/{$ doc.packageFile $}"{% endcode %}
+      <a href="http://bower.io">Bower</a> e.g.
+      {% code %}bower install {$ doc.packageName $}#X.Y.Z{% endcode %}
+    </li>
+    <li>
+      <a href="https://code.angularjs.org/">code.angularjs.org</a>
+      (discouraged for production use) e.g.
+      {% code %}"//code.angularjs.org/X.Y.Z/{$ doc.packageFile $}"{% endcode %}
     </li>
   </ul>
   <p>where X.Y.Z is the AngularJS version you are running.</p>
-  <p>Then load the module in your application by adding it as a dependent module:</p>
+
+  <p>Then, include {$ doc.packageFile | code $} in your HTML:</p>
+
+  {% code %}
+      <script src="path/to/angular.js"></script>
+      <script src="path/to/{$ doc.packageFile $}"></script>
+  {% endcode %}
+
+  <p>Finally, load the module in your application by adding it as a dependent module:</p>
   {% code %}
     angular.module('app', ['{$ doc.name $}']);
   {% endcode %}
@@ -51,7 +62,7 @@
     <td>{$ issueDoc.id | link(issueDoc.name, issueDoc) $}</td>
     <td>
     {% for issue in issueDoc.knownIssues -%}
-      {$ issue | marked $}
+      {$ issue | marked $} {% if not loop.last %}<hr>{% endif %}
     {% endfor -%}
     </td>
   </tr>
@@ -61,6 +72,7 @@
 {% endif %}
 
 
+{% if doc.componentGroups.length %}
 <div class="component-breakdown">
   <h2>Module Components</h2>
   {% for componentGroup in doc.componentGroups %}
@@ -81,6 +93,7 @@
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if doc.usage %}
   <h2>Usage</h2>

docs/config/templates/ngdoc/base.template.html

@@ -1,2 +1,4 @@
+<a href='https://github.com/angular/angular.js/edit/{$ git.version.branch $}/{$ doc.fileInfo.projectRelativePath $}?message=docs({$ (doc.area != "api") and (doc.area + "%2F") or "" $}{$ doc.name $})%3A%20describe%20your%20change...{$ (doc.area == "api") and ("#L" + doc.startingLine) or "" $}' class='improve-docs btn btn-primary'><i class="glyphicon glyphicon-edit">&nbsp;</i>Improve this Doc</a>
+
 {% block content %}
 {% endblock %}

docs/config/templates/ngdoc/lib/deprecated.html

@@ -0,0 +1,9 @@
+{% macro deprecatedBlock(doc) %}{% if doc.deprecated %}
+<div class="alert alert-danger deprecation">
+  <div class="title"><strong>Deprecated:</strong>
+    {% if doc.deprecated.sinceVersion %}<span class="since">(since {$ doc.deprecated.sinceVersion $}) </span>{% endif %}
+    {% if doc.deprecated.removeVersion %}<span class="remove">(to be removed in {$ doc.deprecated.removeVersion $}) </span>{% endif %}
+  </div>
+  {$ doc.deprecated.description | marked $}
+</div>
+{% endif %}{% endmacro %}

docs/config/templates/ngdoc/lib/events.template.html

@@ -1,4 +1,6 @@
 {% import "lib/macros.html" as lib -%}
+{% import "lib/deprecated.html" as x -%}
+
 {%- if doc.events %}
 <h2>Events</h2>
 <ul class="events">
@@ -6,6 +8,9 @@
   <li id="{$ event.name $}">
     <h3>{$ event.name $}</h3>
     <div>{$ event.description | marked $}</div>
+
+    {$ x.deprecatedBlock(event) $}
+
     {%- if event.eventType == 'listen' %}
     <div class="inline">
       <h4>Listen on: {$ event.eventTarget $}</h4>

docs/config/templates/ngdoc/lib/macros.html

@@ -36,7 +36,7 @@
 {%- macro directiveParam(name, type, join, sep) %}
   {%- if type.optional %}[{% endif -%}
   {$ name | dashCase $}{$ join $}{$ type.name $}{$ sep $}
-{%- if type.optional %}]{% endif -%}
+  {%- if type.optional %}]{% endif -%}
 {% endmacro -%}
 
 {%- macro functionSyntax(fn) %}

docs/config/templates/ngdoc/lib/methods.template.html

@@ -1,4 +1,6 @@
 {% import "lib/macros.html" as lib -%}
+{% import "lib/deprecated.html" as x -%}
+
 {%- if doc.methods %}
 <h2>Methods</h2>
 <ul class="methods">
@@ -7,6 +9,8 @@
     <h3>{$ lib.functionSyntax(method) $}</h3>
     <div>{$ method.description | marked $}</div>
 
+    {$ x.deprecatedBlock(method) $}
+
     {% if method.params %}
     <h4>Parameters</h4>
     {$ lib.paramTable(method.params) $}

docs/config/templates/ngdoc/lib/properties.template.html

@@ -1,4 +1,6 @@
 {% import "lib/macros.html" as lib -%}
+{% import "lib/deprecated.html" as x -%}
+
 {%- if doc.properties %}
 <h2>Properties</h2>
 <ul class="properties">
@@ -6,6 +8,7 @@
   <li id="{$ property.name $}">
     <h3>{$ property.name | code $}</h3>
     {$ lib.typeInfo(property) $}
+    {$ x.deprecatedBlock(property) $}
   </li>
   {% endfor -%}
 </ul>