build: api-docs can display incorrect module for entry-point (#16470)

In some cases, an entry-point can export a deprecated NgModule. Currently
if that module is exported after all previous modules, it will show up in the docs
as recommended import. e.g. `import {ScrollDispatchModule} from '@angular/cdk/scrolling';`

This is causing confusion as the non-deprecated module should be used for rendering
the recommended import. This commit ensures that non-deprecated modules are
prioritized over deprecated modules and that specific modules can be explicitly
selected as primary module for an entry-point.

Fixes #16353.

Author: devversion

tools/dgeni/common/decorators.ts

@@ -42,6 +42,12 @@ export function isDeprecatedDoc(doc: any) {
   return (doc.tags && doc.tags.tags || []).some((tag: any) => tag.tagName === 'deprecated');
 }
 
+/** Whether the given document is annotated with the "@docs-primary-module" jsdoc tag. */
+export function isPrimaryModuleDoc(doc: any) {
+  return (doc.tags && doc.tags.tags || [])
+      .some((tag: any) => tag.tagName === 'docs-primary-module');
+}
+
 export function getDirectiveSelectors(classDoc: CategorizedClassDoc) {
   if (!classDoc.directiveMetadata) {
     return;

tools/dgeni/docs-package.ts

@@ -79,6 +79,7 @@ apiDocsPackage.config(function(parseTagsProcessor: any) {
   parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions.concat([
     {name: 'docs-private'},
     {name: 'docs-public'},
+    {name: 'docs-primary-module'},
     {name: 'breaking-change'},
   ]);
 });

tools/dgeni/processors/entry-point-grouper.ts

@@ -5,6 +5,7 @@ import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/Interf
 import {TypeAliasExportDoc} from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc';
 import * as path from 'path';
 import {computeApiDocumentUrl} from '../common/compute-api-url';
+import {isDeprecatedDoc, isPrimaryModuleDoc} from '../common/decorators';
 import {CategorizedClassDoc} from '../common/dgeni-definitions';
 
 export interface ModuleInfo {
@@ -64,8 +65,11 @@ export class EntryPointDoc {
   /** Constants that belong to the entry-point. */
   constants: ConstExportDoc[] = [];
 
-  /** NgModule that defines the current entry-point. */
-  ngModule: CategorizedClassDoc | null = null;
+  /** List of NgModules which are exported in the current entry-point. */
+  exportedNgModules: CategorizedClassDoc[] = [];
+
+  /** NgModule that defines the current entry-point. Null if no module could be found. */
+  ngModule: CategorizedClassDoc|null = null;
 
   constructor(name: string) {
     this.name = name;
@@ -117,7 +121,12 @@ export class EntryPointGrouper implements Processor {
       } else if (doc.isService) {
         entryPoint.services.push(doc);
       } else if (doc.isNgModule) {
-        entryPoint.ngModule = doc;
+        entryPoint.exportedNgModules.push(doc);
+        // If the module is explicitly marked as primary module using the "@docs-primary-module"
+        // annotation, we set is as primary entry-point module.
+        if (isPrimaryModuleDoc(doc)) {
+          entryPoint.ngModule = doc;
+        }
       } else if (doc.docType === 'class') {
         entryPoint.classes.push(doc);
       } else if (doc.docType === 'interface') {
@@ -131,6 +140,25 @@ export class EntryPointGrouper implements Processor {
       }
     });
 
+    // For each entry-point we determine a primary NgModule that defines the entry-point
+    // if no primary module has been explicitly declared (using "@docs-primary-module").
+    entryPoints.forEach(entryPoint => {
+      if (entryPoint.ngModule !== null) {
+        return;
+      }
+
+      // Usually the first module that is not deprecated is used, but in case there are
+      // only deprecated modules, the last deprecated module is used. We don't want to
+      // always skip deprecated modules as they could be still needed for documentation
+      // of a deprecated entry-point.
+      for (let ngModule of entryPoint.exportedNgModules) {
+        entryPoint.ngModule = ngModule;
+        if (!isDeprecatedDoc(ngModule)) {
+          break;
+        }
+      }
+    });
+
     return Array.from(entryPoints.values());
   }
 }