chore(docs): deprecation notices for methods and properties

Closes #15351
Closes #15394

Author: petebacondarwin

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,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 %}
-  </div>
-{% 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>
+    <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 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/examples/runnableExample.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 @@ <h2 id="known-issues">Known Issues</h2>
 {% 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/git/api/api.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 @@ <h2 id="known-issues">Known Issues</h2>
     <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 @@ <h2 id="known-issues">Known Issues</h2>
 {% endif %}
 
 
+{% if doc.componentGroups.length %}
 <div class="component-breakdown">
   <h2>Module Components</h2>
   {% for componentGroup in doc.componentGroups %}
@@ -81,6 +93,7 @@ <h3 class="component-heading" id="{$ componentGroup.groupType | dashCase $}">{$
   </div>
   {% endfor %}
 </div>
+{% endif %}
 
 {% if doc.usage %}
   <h2>Usage</h2>