build(aio): add processor to migrate legacy tags `@whatItDoes` and `@howToUse` (#22401)

See https://github.com/angular/angular/issues/22135#issuecomment-367632372

PR Close #22401

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

@@ -14,6 +14,7 @@ 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/convertPrivateClassesToInterfaces'))
   .processor(require('./processors/generateApiListDoc'))
   .processor(require('./processors/addNotYetDocumentedProperty'))

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

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,66 @@
+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' }
+    ]);
+  });
+});