docs(deprecations): add deprecation page

docs_app/content/file-not-found.md

@@ -7,4 +7,3 @@
         <p>We're sorry. The page you are looking for cannot be found.</p>
     </div>
 </div>
-<aio-file-not-found-search></aio-file-not-found-search>

docs_app/content/navigation.json

@@ -1,56 +1,60 @@
 {
-  "TopBar": [
-    {
-      "url": "guide/overview",
-      "title": "Overview"
-    },
-    {
-      "url": "api",
-      "title": "Reference"
-    },
-    {
-      "url": "guide/v6/migration",
-      "title": "Migration"
-    },
-    {
-      "url": "team",
-      "title": "Team"
-    }
-  ],
+	"TopBar": [
+		{
+			"url": "guide/overview",
+			"title": "Overview"
+		},
+		{
+			"url": "api",
+			"title": "Reference"
+		},
+		{
+			"url": "guide/v6/migration",
+			"title": "Migration"
+		},
+		{
+			"url": "team",
+			"title": "Team"
+		}
+	],
 
-  "TopBarNarrow": [],
+	"TopBarNarrow": [],
 
-  "SideNav": [
-    {
-      "url": "guide/overview",
-      "title": "Overview",
-      "tooltip": "RxJS Overview"
-    },
-    {
-      "url": "guide/installation",
-      "title": "Installation",
-      "tooltip": "Installation"
-    },
-    {
-      "url": "api",
-      "title": "Reference",
-      "tooltip": "RxJS Reference"
-    },
-    {
-      "title": "About Version 6",
-      "children": [
-        {
-          "url": "guide/v6/migration",
-          "title": "Migration"
-        }
-      ]
-    },
-    {
-      "url": "code-of-conduct",
-      "title": "Code of Conduct",
-      "tooltip": "Code of Conduct"
-    }
-  ],
-  "docVersions": []
+	"SideNav": [
+		{
+			"url": "guide/overview",
+			"title": "Overview",
+			"tooltip": "RxJS Overview"
+		},
+		{
+			"url": "guide/installation",
+			"title": "Installation",
+			"tooltip": "Installation"
+		},
+		{
+			"url": "api",
+			"title": "Reference",
+			"tooltip": "RxJS Reference"
+		},
+		{
+			"title": "About Version 6",
+			"children": [
+				{
+					"url": "guide/v6/migration",
+					"title": "Migration"
+				},
+				{
+					"url": "api/deprecations",
+					"title": "Deprecations",
+					"tooltip": "List of Deprecations"
+				}
+			]
+		},
+		{
+			"url": "code-of-conduct",
+			"title": "Code of Conduct",
+			"tooltip": "Code of Conduct"
+		}
+	],
+	"docVersions": []
 }
-

docs_app/src/app/navigation/navigation.service.ts

@@ -95,7 +95,7 @@ export class NavigationService {
       this.location.currentPath,
 
       (navMap, url) => {
-        const urlKey = url.startsWith('api/') ? 'api' : url;
+        const urlKey = url.startsWith('api/') && !url.endsWith('deprecations') ? 'api' : url;
         return navMap.get(urlKey) || { '' : { view: '', url: urlKey, nodes: [] }};
       })
       .pipe(publishReplay(1));

docs_app/tools/transforms/angular-api-package/index.js

@@ -19,6 +19,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   .processor(require('./processors/splitDescription'))
   .processor(require('./processors/convertPrivateClassesToInterfaces'))
   .processor(require('./processors/generateApiListDoc'))
+  .processor(require('./processors/generateDeprecationsListDoc'))
   .processor(require('./processors/addNotYetDocumentedProperty'))
   .processor(require('./processors/mergeDecoratorDocs'))
   .processor(require('./processors/extractDecoratedClasses'))
@@ -41,7 +42,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
    * more Angular specific API types, such as decorators and directives.
    */
   .factory(function API_DOC_TYPES_TO_RENDER(EXPORT_DOC_TYPES) {
-    return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module']);
+    return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'module', 'deprecation']);
   })
 
   /**
@@ -146,11 +147,12 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     splitDescription.docTypes = API_DOC_TYPES;
   })
 
-  .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
+  .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc, generateDeprecationListDoc) {
 
     const API_SEGMENT = 'api';
 
     generateApiListDoc.outputFolder = API_SEGMENT;
+    generateDeprecationListDoc.outputFolder = API_SEGMENT;
 
     computePathsProcessor.pathTemplates.push({
       docTypes: ['module'],

docs_app/tools/transforms/angular-api-package/processors/generateDeprecationsListDoc.js

@@ -0,0 +1,26 @@
+module.exports = function generateDeprecationListDoc() {
+
+  return {
+    $runAfter: ['extra-docs-added'],
+    $runBefore: ['rendering-docs'],
+    outputFolder: null,
+    $process: function(docs) {
+      docs.push({
+        docType: 'deprecation',
+        template: 'json-doc.template.json',
+        path: this.outputFolder + '/deprecations',
+        outputPath: this.outputFolder + '/deprecations.json',
+        data: docs
+          .filter(doc => doc.deprecated)
+          .map(doc => {
+            return {
+              name: doc.name,
+              type: doc.docType,
+              path: doc.path,
+              text: doc.deprecated
+            };
+          })
+      });
+    }
+  };
+};

docs_app/tools/transforms/templates/api/deprecation.template.html

@@ -0,0 +1,20 @@
+{% block overview %}
+<section class="deprecations">
+  <h1>Deprecations</h1>
+  <p class="important">The API listed below will be removed in the next major release!</p>
+  <table>
+{% for deprecation in doc.data %}
+    <tr>
+        <td>
+            <a href="{$ deprecation.path $}">{$ deprecation.name $}</a>
+        </td>
+        <td>
+            {$ deprecation.text $}
+        </td>
+    </tr>
+    {% endfor %}
+  </table>
+</section>
+{% endblock %}
+
+

src/internal/Observable.ts

@@ -257,7 +257,7 @@ export class Observable<T> implements Subscribable<T> {
     }) as Promise<void>;
   }
 
-  /** @deprecated This is an internal implementation detail, do not use. */
+  /** @internal This is an internal implementation detail, do not use. */
   _subscribe(subscriber: Subscriber<any>): TeardownLogic {
     const { source } = this;
     return source && source.subscribe(subscriber);

src/internal/Subscriber.ts

@@ -314,7 +314,7 @@ class SafeSubscriber<T> extends Subscriber<T> {
     return false;
   }
 
-  /** @deprecated This is an internal implementation detail, do not use. */
+  /** @internal This is an internal implementation detail, do not use. */
   _unsubscribe(): void {
     const { _parentSubscriber } = this;
     this._context = null;

src/internal/observable/empty.ts

@@ -54,7 +54,7 @@ export const EMPTY = new Observable<never>(subscriber => subscriber.complete());
  * @static true
  * @name empty
  * @owner Observable
- * @deprecated Deprecated in favor of using EMPTY constant.
+ * @deprecated Deprecated in favor of using {@link index/EMPTY} constant.
  */
 export function empty(scheduler?: SchedulerLike) {
   return scheduler ? emptyScheduled(scheduler) : EMPTY;

src/internal/observable/never.ts

@@ -31,7 +31,7 @@ import { noop } from '../util/noop';
 export const NEVER = new Observable<never>(noop);
 
 /**
- * @deprecated Deprecated in favor of using NEVER constant.
+ * @deprecated Deprecated in favor of using {@link NEVER} constant.
  */
 export function never () {
   return NEVER;

src/internal/operators/combineLatest.ts

@@ -39,7 +39,7 @@ export function combineLatest<T, TOther, R>(array: ObservableInput<TOther>[], pr
 /* tslint:enable:max-line-length */
 
 /**
- * @deprecated Deprecated in favor of static combineLatest.
+ * @deprecated Deprecated in favor of static {@link combineLatest}.
  */
 export function combineLatest<T, R>(...observables: Array<ObservableInput<any> |
                                                     Array<ObservableInput<any>> |

src/internal/operators/concat.ts

@@ -22,7 +22,7 @@ export function concat<T, R>(...observables: Array<ObservableInput<any> | Schedu
 /* tslint:enable:max-line-length */
 
 /**
- * @deprecated Deprecated in favor of static concat.
+ * @deprecated Deprecated in favor of static {@link concat}.
  */
 export function concat<T, R>(...observables: Array<ObservableInput<any> | SchedulerLike>): OperatorFunction<T, R> {
   return (source: Observable<T>) => source.lift.call(concatStatic<T, R>(source, ...observables));

src/internal/operators/merge.ts

@@ -34,7 +34,7 @@ export function merge<T, R>(...observables: Array<ObservableInput<any> | Schedul
 /* tslint:enable:max-line-length */
 
 /**
- * @deprecated Deprecated in favor of static merge.
+ * @deprecated Deprecated in favor of static {@link merge}.
  */
 export function merge<T, R>(...observables: Array<ObservableInput<any> | SchedulerLike | number>): OperatorFunction<T, R> {
   return (source: Observable<T>) => source.lift.call(mergeStatic(source, ...observables));

src/internal/operators/race.ts

@@ -21,7 +21,7 @@ export function race<T, R>(...observables: Array<Observable<any> | Array<Observa
  * @return {Observable} An Observable that mirrors the output of the first Observable to emit an item.
  * @method race
  * @owner Observable
- * @deprecated Deprecated in favor of static race.
+ * @deprecated Deprecated in favor of static {@link race}.
  */
 export function race<T>(...observables: Array<Observable<T> | Array<Observable<T>>>): MonoTypeOperatorFunction<T> {
   return function raceOperatorFunction(source: Observable<T>) {

src/internal/operators/zip.ts

@@ -34,7 +34,7 @@ export function zip<T, TOther, R>(array: Array<ObservableInput<TOther>>, project
 /* tslint:enable:max-line-length */
 
 /**
- * @deprecated Deprecated in favor of static zip.
+ * @deprecated Deprecated in favor of static {@link zip}.
  */
 export function zip<T, R>(...observables: Array<ObservableInput<any> | ((...values: Array<any>) => R)>): OperatorFunction<T, R> {
   return function zipOperatorFunction(source: Observable<T>) {