build(aio): compute stability and deprecate `@stable` tag (#22674)

Closes #22635

PR Close #22674

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

@@ -30,6 +30,24 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   .processor(require('./processors/filterPrivateDocs'))
   .processor(require('./processors/computeSearchTitle'))
   .processor(require('./processors/simplifyMemberAnchors'))
+  .processor(require('./processors/computeStability'))
+
+  /**
+   * These are the API doc types that will be rendered to actual files.
+   * This is a super set of the exported docs, since we convert some classes to
+   * 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']);
+  })
+
+  /**
+   * These are the doc types that are API docs, including ones that will be merged into container docs,
+   * such as members and overloads.
+   */
+  .factory(function API_DOC_TYPES(API_DOC_TYPES_TO_RENDER) {
+    return API_DOC_TYPES_TO_RENDER.concat(['member', 'function-overload']);
+  })
 
   // Where do we get the source files?
   .config(function(readTypeScriptModules, readFilesProcessor, collectExamples, tsParser) {
@@ -92,9 +110,10 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
         parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs')));
   })
 
-  .config(function(splitDescription, EXPORT_DOC_TYPES) {
+  .config(function(computeStability, splitDescription, EXPORT_DOC_TYPES, API_DOC_TYPES) {
+    computeStability.docTypes = EXPORT_DOC_TYPES;
     // Only split the description on the API docs
-    splitDescription.docTypes = EXPORT_DOC_TYPES.concat(['member', 'function-overload']);
+    splitDescription.docTypes = API_DOC_TYPES;
   })
 
   .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) {
@@ -124,12 +143,9 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   })
 
 
-  .config(function(convertToJsonProcessor, postProcessHtml, EXPORT_DOC_TYPES, autoLinkCode) {
+  .config(function(convertToJsonProcessor, postProcessHtml, API_DOC_TYPES_TO_RENDER, API_DOC_TYPES, autoLinkCode) {
-    const DOCS_TO_CONVERT = EXPORT_DOC_TYPES.concat([
+    convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(API_DOC_TYPES_TO_RENDER);
-      'decorator', 'directive', 'pipe', 'module'
+    postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(API_DOC_TYPES_TO_RENDER);
-    ]);
+    autoLinkCode.docTypes = API_DOC_TYPES;
-    convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
-    postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
-    autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member', 'function-overload']);
     autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
   });

aio/tools/transforms/angular-api-package/processors/computeStability.js

@@ -0,0 +1,18 @@
+module.exports = function computeStability(log, createDocMessage) {
+  return {
+    docTypes: [],
+    $runAfter: ['tags-extracted'],
+    $runBefore: ['rendering-docs'],
+    $process(docs) {
+      docs.forEach(doc => {
+        if (this.docTypes.indexOf(doc.docType) !== -1 &&
+            doc.experimental === undefined &&
+            doc.deprecated === undefined &&
+            doc.stable === undefined) {
+          log.debug(createDocMessage('Adding stable property', doc));
+          doc.stable = true;
+        }
+      });
+    }
+  };
+};

aio/tools/transforms/angular-api-package/processors/computeStability.spec.js

@@ -0,0 +1,82 @@
+const log = require('dgeni/lib/mocks/log')(false);
+const createDocMessage = require('dgeni-packages/base/services/createDocMessage')();
+const computeStability = require('./computeStability')(log, createDocMessage);
+const testPackage = require('../../helpers/test-package');
+const Dgeni = require('dgeni');
+
+describe('computeStability processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('computeStability');
+    expect(processor.$process).toBeDefined();
+  });
+
+  it('should run before the correct processor', () => {
+    expect(computeStability.$runBefore).toEqual(['rendering-docs']);
+  });
+
+  it('should run after the correct processor', () => {
+    expect(computeStability.$runAfter).toEqual(['tags-extracted']);
+  });
+
+  it('should compute stability based on the existence of experimental and deprecated tags', () => {
+    computeStability.docTypes = ['test'];
+    const docs = [
+      { docType: 'test' },
+      { docType: 'test', experimental: undefined },
+      { docType: 'test', experimental: true },
+      { docType: 'test', experimental: '' },
+      { docType: 'test', deprecated: undefined },
+      { docType: 'test', deprecated: true },
+      { docType: 'test', deprecated: '' },
+      { docType: 'test', experimental: true, deprecated: true },
+    ];
+    computeStability.$process(docs);
+    expect(docs.map(doc => doc.stable)).toEqual([
+      true,
+      true,
+      undefined,
+      undefined,
+      true,
+      undefined,
+      undefined,
+      undefined
+    ]);
+  });
+
+  it('should ignore docs that are not in the docTypes list', () => {
+    computeStability.docTypes = ['test1', 'test2'];
+    const docs = [
+      { docType: 'test1' },
+      { docType: 'test2' },
+      { docType: 'test3' },
+      { docType: 'test4' },
+    ];
+    computeStability.$process(docs);
+    expect(docs.map(doc => doc.stable)).toEqual([
+      true,
+      true,
+      undefined,
+      undefined
+    ]);
+  });
+
+  it('should not ignore docs where `stable` has already been defined', () => {
+    computeStability.docTypes = ['test'];
+    const docs = [
+      { docType: 'test' },
+      { docType: 'test', stable: true },
+      { docType: 'test', stable: '' },
+      { docType: 'test', stable: undefined },
+    ];
+    computeStability.$process(docs);
+    expect(docs.map(doc => doc.stable)).toEqual([
+      true,
+      true,
+      '',
+      true
+    ]);
+  });
+});

aio/tools/transforms/angular-api-package/tag-defs/stable.js

@@ -1,3 +1,10 @@
-module.exports = function() {
+module.exports = function(log, createDocMessage) {
-  return {name: 'stable'};
+  return {
+    name: 'stable',
+    transforms(doc, tag, value) {
+      log.warn(createDocMessage('Deprecated `@stable` tag found', doc));
+      log.warn('PLEASE REMOVE - its value is now computed.');
+      return value;
+    }
+  };
 };