docs: component-grouper does not always include components (#13079)

* Currently we group the Dgeni docs by entry-points (we just call it *grouping by components*). Technically there are "component groups" that do not even include any component/directive (e.g. `cdk/coercion`, `cdk/platform`). This renames the component grouper to `entry point grouper`.
* No longer displays interfaces, classes, type-aliases etc. as `additional` "parts of an entry-point". (As mentioned above; sometimes classes are the primary export of an entry-point).

Author: devversion

tools/dgeni/index.ts

@@ -5,7 +5,7 @@ import {DocsPrivateFilter} from './processors/docs-private-filter';
 import {Categorizer} from './processors/categorizer';
 import {FilterDuplicateExports} from './processors/filter-duplicate-exports';
 import {MergeInheritedProperties} from './processors/merge-inherited-properties';
-import {ComponentGrouper} from './processors/component-grouper';
+import {EntryPointGrouper} from './processors/entry-point-grouper';
 import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTypeScriptModules';
 import {TsParser} from 'dgeni-packages/typescript/services/TsParser';
 import {sync as globSync} from 'glob';
@@ -62,8 +62,8 @@ apiDocsPackage.processor(new DocsPrivateFilter());
 // Processor that appends categorization flags to the docs, e.g. `isDirective`, `isNgModule`, etc.
 apiDocsPackage.processor(new Categorizer());
 
-// Processor to group components into top-level groups such as "Tabs", "Sidenav", etc.
-apiDocsPackage.processor(new ComponentGrouper());
+// Processor to group docs into top-level entry-points such as "tabs", "sidenav", etc.
+apiDocsPackage.processor(new EntryPointGrouper());
 
 // Configure the log level of the API docs dgeni package.
 apiDocsPackage.config((log: any) => log.level = 'info');
@@ -82,7 +82,7 @@ apiDocsPackage.config((log: any) => patchLogService(log));
 // Configure the output path for written files (i.e., file names).
 apiDocsPackage.config((computePathsProcessor: any) => {
   computePathsProcessor.pathTemplates = [{
-    docTypes: ['componentGroup'],
+    docTypes: ['entry-point'],
     pathTemplate: '${name}',
     outputPathTemplate: '${name}.html',
   }];

tools/dgeni/processors/component-grouper.ts renamed to tools/dgeni/processors/entry-point-grouper.ts

@@ -1,23 +1,23 @@
 import {DocCollection, Document, Processor} from 'dgeni';
+import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
 import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/InterfaceExportDoc';
 import {TypeAliasExportDoc} from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc';
-import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
-import {CategorizedClassDoc} from '../common/dgeni-definitions';
 import * as path from 'path';
+import {CategorizedClassDoc} from '../common/dgeni-definitions';
 
-/** Component group data structure. */
-export class ComponentGroup {
+/** Document type for an entry-point. */
+export class EntryPointDoc {
 
   /** Unique document type for Dgeni. */
-  docType = 'componentGroup';
+  docType = 'entry-point';
 
   /** Name of the component group. */
   name: string;
 
-  /** Display name of the component group */
+  /** Display name of the entry-point. */
   displayName: string;
 
-  /** Module import path for the component group. */
+  /** Module import path for the entry-point. */
   moduleImportPath: string;
 
   /** Name of the package, either material or cdk */
@@ -26,10 +26,10 @@ export class ComponentGroup {
   /** Display name of the package. */
   packageDisplayName: string;
 
-  /** Unique id for the component group. */
+  /** Unique id for the entry-point. */
   id: string;
 
-  /** Known aliases for the component group. */
+  /** Known aliases for the entry-point. This is only needed for the `computeIdsProcessor`. */
   aliases: string[] = [];
 
   /** List of categorized class docs that are defining a directive. */
@@ -38,38 +38,37 @@ export class ComponentGroup {
   /** List of categorized class docs that are defining a service. */
   services: CategorizedClassDoc[] = [];
 
-  /** Additional classes that belong to the component group. */
-  additionalClasses: CategorizedClassDoc[] = [];
+  /** Classes that belong to the entry-point. */
+  classes: CategorizedClassDoc[] = [];
 
-  /** Additional interfaces that belong to the component group. */
-  additionalInterfaces: InterfaceExportDoc[] = [];
+  /** Interfaces that belong to the entry-point. */
+  interfaces: InterfaceExportDoc[] = [];
 
-  /** Additional type aliases that belong to the component group. */
-  additionalTypeAliases: TypeAliasExportDoc[] = [];
+  /** Type aliases that belong to the entry-point. */
+  typeAliases: TypeAliasExportDoc[] = [];
 
-  /** Additional functions that belong to the component group. */
-  additionalFunctions: FunctionExportDoc[] = [];
+  /** Functions that belong to the entry-point. */
+  functions: FunctionExportDoc[] = [];
 
-  /** NgModule that defines the current component group. */
+  /** NgModule that defines the current entry-point. */
   ngModule: CategorizedClassDoc | null = null;
 
   constructor(name: string) {
     this.name = name;
-    this.id = `component-group-${name}`;
+    this.id = `entry-point-${name}`;
   }
 }
 
 /**
- * Processor to group docs into top-level "Components" WRT material design, e.g., "Button", "Tabs",
- * where each group may conists of several directives and services.
+ * Processor to group docs into entry-points that consist of directives, component, classes,
+ * interfaces, functions or type aliases.
  */
-export class ComponentGrouper implements Processor {
-  name = 'component-grouper';
+export class EntryPointGrouper implements Processor {
+  name = 'entry-point-grouper';
   $runBefore = ['docs-processed'];
 
   $process(docs: DocCollection) {
-    // Map of group name to group instance.
-    const groups = new Map<string, ComponentGroup>();
+    const entryPoints = new Map<string, EntryPointDoc>();
 
     docs.forEach(doc => {
       const documentInfo = getDocumentPackageInfo(doc);
@@ -78,41 +77,41 @@ export class ComponentGrouper implements Processor {
       const packageDisplayName = documentInfo.packageName === 'cdk' ? 'CDK' : 'Material';
 
       const moduleImportPath = `@angular/${packageName}/${documentInfo.entryPointName}`;
-      const groupName = packageName + '-' + documentInfo.name;
+      const entryPointName = packageName + '-' + documentInfo.name;
 
-      // Get the group for this doc, or, if one does not exist, create it.
-      let group;
-      if (groups.has(groupName)) {
-        group = groups.get(groupName)!;
+      // Get the entry-point for this doc, or, if one does not exist, create it.
+      let entryPoint;
+      if (entryPoints.has(entryPointName)) {
+        entryPoint = entryPoints.get(entryPointName)!;
       } else {
-        group = new ComponentGroup(groupName);
-        groups.set(groupName, group);
+        entryPoint = new EntryPointDoc(entryPointName);
+        entryPoints.set(entryPointName, entryPoint);
       }
 
-      group.displayName = documentInfo.name;
-      group.moduleImportPath = moduleImportPath;
-      group.packageName = packageName;
-      group.packageDisplayName = packageDisplayName;
+      entryPoint.displayName = documentInfo.name;
+      entryPoint.moduleImportPath = moduleImportPath;
+      entryPoint.packageName = packageName;
+      entryPoint.packageDisplayName = packageDisplayName;
 
-      // Put this doc into the appropriate list in this group.
+      // Put this doc into the appropriate list in the entry-point doc.
       if (doc.isDirective) {
-        group.directives.push(doc);
+        entryPoint.directives.push(doc);
       } else if (doc.isService) {
-        group.services.push(doc);
+        entryPoint.services.push(doc);
       } else if (doc.isNgModule) {
-        group.ngModule = doc;
+        entryPoint.ngModule = doc;
       } else if (doc.docType === 'class') {
-        group.additionalClasses.push(doc);
+        entryPoint.classes.push(doc);
       } else if (doc.docType === 'interface') {
-        group.additionalInterfaces.push(doc);
+        entryPoint.interfaces.push(doc);
       } else if (doc.docType === 'type-alias') {
-        group.additionalTypeAliases.push(doc);
+        entryPoint.typeAliases.push(doc);
       } else if (doc.docType === 'function') {
-        group.additionalFunctions.push(doc);
+        entryPoint.functions.push(doc);
       }
     });
 
-    return Array.from(groups.values());
+    return Array.from(entryPoints.values());
   }
 }
 
@@ -127,8 +126,9 @@ function getDocumentPackageInfo(doc: Document) {
   const pathSegments = path.relative(basePath, filePath).split(path.sep);
   let groupName = pathSegments[1];
 
-  // For the ripples there should be a component group in the docs. Even it's not a
-  // secondary-entry point it can be still documented with its own `material-ripple.html` file.
+  // The ripples are technically part of the `@angular/material/core` entry-point, but we
+  // want to show the ripple API separately in the docs. In order to archive this, we treat
+  // the ripple folder as its own entry-point.
   if (pathSegments[1] === 'core' && pathSegments[2] === 'ripple') {
     groupName = 'ripple';
   }

tools/dgeni/templates/componentGroup.template.html renamed to tools/dgeni/templates/entry-point.template.html

@@ -59,32 +59,32 @@ <h3 id="directives" class="docs-header-link docs-api-h3">
     {% endfor %}
   {%- endif -%}
 
-  {%- if doc.additionalClasses.length -%}
-    <h3 id="additional_classes" class="docs-header-link docs-api-h3">
-      <span header-link="additional_classes"></span>
-      Additional classes
+  {%- if doc.classes.length -%}
+    <h3 id="classes" class="docs-header-link docs-api-h3">
+      <span header-link="classes"></span>
+      Classes
     </h3>
-    {% for other in doc.additionalClasses %}
+    {% for other in doc.classes %}
       {$ class(other) $}
     {% endfor %}
   {%- endif -%}
 
-  {%- if doc.additionalInterfaces.length -%}
-    <h3 id="additional_interfaces" class="docs-header-link docs-api-h3">
-      <span header-link="additional_interfaces"></span>
-      Additional interfaces
+  {%- if doc.interfaces.length -%}
+    <h3 id="interfaces" class="docs-header-link docs-api-h3">
+      <span header-link="interfaces"></span>
+      Interfaces
     </h3>
-    {% for item in doc.additionalInterfaces %}
+    {% for item in doc.interfaces %}
       {$ interface(item) $}
     {% endfor %}
   {%- endif -%}
 
-  {%- if doc.additionalFunctions.length -%}
-    <h3 id="additional_functions" class="docs-header-link docs-api-h3">
-      <span header-link="additional_functions"></span>
-      Additional functions
+  {%- if doc.functions.length -%}
+    <h3 id="functions" class="docs-header-link docs-api-h3">
+      <span header-link="functions"></span>
+      Functions
     </h3>
-    {% for item in doc.additionalFunctions %}
+    {% for item in doc.functions %}
       {#
         Since the function docs have a similar structure as method docs, we use
         the method template.
@@ -93,12 +93,12 @@ <h3 id="additional_functions" class="docs-header-link docs-api-h3">
     {% endfor %}
   {%- endif -%}
 
-  {%- if doc.additionalTypeAliases.length -%}
-    <h3 id="additional_type_aliases" class="docs-header-link docs-api-h3">
-      <span header-link="additional_type_aliases"></span>
-      Additional type aliases
+  {%- if doc.typeAliases.length -%}
+    <h3 id="type_aliases" class="docs-header-link docs-api-h3">
+      <span header-link="type_aliases"></span>
+      Type aliases
     </h3>
-    {% for item in doc.additionalTypeAliases %}
+    {% for item in doc.typeAliases %}
       {$ typeAlias(item) $}
     {% endfor %}
   {%- endif -%}