build(docs-infra): remove legacy jsdoc tag processing (#26039)

PR Close #26039

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

@@ -14,7 +14,6 @@ const { API_SOURCE_PATH, API_TEMPLATES_PATH, requireFolder } = require('../confi
 module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
 
   // Register the processors
-  .processor(require('./processors/migrateLegacyJSDocTags'))
   .processor(require('./processors/splitDescription'))
   .processor(require('./processors/convertPrivateClassesToInterfaces'))
   .processor(require('./processors/generateApiListDoc'))

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

@@ -42,7 +42,7 @@ const {mergeProperties} = require('../../helpers/utils');
  *
  * Finally we want to capture the documentation attached to the call signature interface of the
  * associated decorator (1). We copy across the properties that we care about from this call
- * signature (e.g. description, whatItDoes and howToUse).
+ * signature (e.g. `description` and `usageNotes`).
  */
 
 module.exports = function mergeDecoratorDocs(log) {

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

@@ -1,36 +0,0 @@
-module.exports = function migrateLegacyJSDocTags(log, createDocMessage) {
-  return {
-    $runAfter: ['tags-extracted'],
-    $runBefore: ['processing-docs'],
-    $process(docs) {
-      let migrated = false;
-      docs.forEach(doc => {
-        if (doc.howToUse) {
-          if (doc.usageNotes) {
-            throw new Error(createDocMessage('`@usageNotes` and the deprecated `@howToUse` are not allowed on the same doc', doc));
-          }
-          log.debug(createDocMessage('Using deprecated `@howToUse` tag as though it was `@usageNotes` tag', doc));
-          doc.usageNotes = doc.howToUse;
-          doc.howToUse = null;
-          migrated = true;
-        }
-
-        if (doc.whatItDoes) {
-          log.debug(createDocMessage('Merging the content of `@whatItDoes` tag into the description.', doc));
-          if (doc.description) {
-            doc.description = `${doc.whatItDoes}\n\n${doc.description}`;
-          } else {
-            doc.description = doc.whatItDoes;
-          }
-          doc.whatItDoes = null;
-          migrated = true;
-        }
-      });
-
-      if (migrated) {
-        log.warn('Some deprecated tags were migrated.');
-        log.warn('This automatic handling will be removed in a future version of the doc generation.\n');
-      }
-    }
-  };
-};

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

@@ -1,66 +0,0 @@
-const testPackage = require('../../helpers/test-package');
-const processorFactory = require('./migrateLegacyJSDocTags');
-const log = require('dgeni/lib/mocks/log')(false);
-const createDocMessage = require('dgeni-packages/base/services/createDocMessage')();
-const Dgeni = require('dgeni');
-
-describe('migrateLegacyJSDocTags processor', () => {
-
-  it('should be available on the injector', () => {
-    const dgeni = new Dgeni([testPackage('angular-api-package')]);
-    const injector = dgeni.configureInjector();
-    const processor = injector.get('migrateLegacyJSDocTags');
-    expect(processor.$process).toBeDefined();
-  });
-
-  it('should run before the correct processor', () => {
-    const processor = processorFactory(log, createDocMessage);
-    expect(processor.$runBefore).toEqual(['processing-docs']);
-  });
-
-  it('should run after the correct processor', () => {
-    const processor = processorFactory(log, createDocMessage);
-    expect(processor.$runAfter).toEqual(['tags-extracted']);
-  });
-
-  it('should migrate `howToUse` property to `usageNotes` property', () => {
-    const processor = processorFactory(log, createDocMessage);
-    const docs = [
-      { howToUse: 'this is how to use it' }
-    ];
-    processor.$process(docs);
-    expect(docs[0].howToUse).toBe(null);
-    expect(docs[0].usageNotes).toEqual('this is how to use it');
-  });
-
-  it('should migrate `whatItDoes` property to the `description`', () => {
-    const processor = processorFactory(log, createDocMessage);
-    const docs = [
-      { whatItDoes: 'what it does' },
-      { whatItDoes: 'what it does', description: 'the description' },
-      { description: 'the description' }
-    ];
-    processor.$process(docs);
-    expect(docs[0].whatItDoes).toBe(null);
-    expect(docs[0].description).toEqual('what it does');
-
-    expect(docs[1].whatItDoes).toBe(null);
-    expect(docs[1].description).toEqual('what it does\n\nthe description');
-
-    expect(docs[2].whatItDoes).toBeUndefined();
-    expect(docs[2].description).toEqual('the description');
-  });
-
-  it('should ignore docs that have neither `howToUse` nor `whatItDoes` properties', () => {
-    const processor = processorFactory(log, createDocMessage);
-    const docs = [
-      { },
-      { description: 'the description' }
-    ];
-    processor.$process(docs);
-    expect(docs).toEqual([
-      { },
-      { description: 'the description' }
-    ]);
-  });
-});

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

@@ -5,7 +5,7 @@
  */
 module.exports = function splitDescription() {
   return {
-    $runAfter: ['tags-extracted', 'migrateLegacyJSDocTags'],
+    $runAfter: ['tags-extracted'],
     $runBefore: ['processing-docs'],
     docTypes: [],
     $process(docs) {

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

@@ -18,7 +18,7 @@ describe('splitDescription processor', () => {
 
   it('should run after the correct processor', () => {
     const processor = processorFactory();
-    expect(processor.$runAfter).toEqual(['tags-extracted', 'migrateLegacyJSDocTags']);
+    expect(processor.$runAfter).toEqual(['tags-extracted']);
   });
 
   it('should split the `description` property into the first paragraph and other paragraphs', () => {

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

@@ -1,11 +0,0 @@
-module.exports = function(log, createDocMessage) {
-  return {
-    name: 'howToUse',
-    deprecated: true,
-    transforms(doc, tag, value) {
-      log.warn(createDocMessage('Deprecated `@howToUse` tag found', doc));
-      log.warn('PLEASE FIX by renaming to `@usageNotes.');
-      return value;
-    }
-  };
-};

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

@@ -1,11 +0,0 @@
-module.exports = function(log, createDocMessage) {
-  return {
-    name: 'whatItDoes',
-    deprecated: true,
-    transforms(doc, tag, value) {
-      log.warn(createDocMessage('Deprecated `@whatItDoes` tag found', doc));
-      log.warn('PLEASE FIX by adding the content of this tag as the first paragraph of the `@description` tag.');
-      return value;
-    }
-  };
-};

aio/tools/transforms/templates/README.md

@@ -8,10 +8,9 @@ other templates. Templates can also import macros from other template files.
 When extending a template, parent must declare blocks that can be overridden by the
 child. The template extension hierarchy looks like this (with declared blocks in parentheses):
 
-- layout/base.template.html (base)
+- layout/base.template.html (bread-crumbs, header, embedded contents and body)
-  - module.template.html
+  - package.template.html
-  - layout/api-base.template.html (jumpNav, jumpNavLinks, whatItDoes, infoBar, securityConsiderations,
+  - export-base.template.html (short-description, security-notes, deprecation, overview, see-also, details, usageNotes)
-    deprecationNotes, howToUse, details)
     - class.template.html
       - directive.template.html
     - enum.template.html
@@ -21,8 +20,10 @@ child. The template extension hierarchy looks like this (with declared blocks in
     - decorator.template.html
     - function.template.html
     - interface.template.html
+      - value-module.template.html
     - type-alias.template.html
     - pipe.template.html
+    - ngmodule.template.html
 
 # Doc Properties