docs: show interfaces (#8376)

Also adds documentation for the `RippleGlobalOptions`

Closes #8298

src/lib/core/ripple/ripple-renderer.ts

@@ -85,7 +85,7 @@ export class RippleRenderer {
     }
 
     const radius = config.radius || distanceToFurthestCorner(x, y, containerRect);
-    const duration = RIPPLE_FADE_IN_DURATION * (1 / (config.speedFactor || 1));
+    const duration = RIPPLE_FADE_IN_DURATION / (config.speedFactor || 1);
     const offsetX = x - containerRect.left;
     const offsetY = y - containerRect.top;
 

src/lib/core/ripple/ripple.md

@@ -85,9 +85,4 @@ const globalRippleConfig: RippleGlobalOptions = {
 })
 ```
 
-All currently available global options are shown here:
-
-| Name            | Type    | Description                               |
-| --------------- | ------- | ----------------------------------------- |
-| disabled        | boolean | Whether ripples should show or not.       |
-| baseSpeedFactor | number  | Factor to adjust ripple speed.            |
+All available global options can be seen in the `RippleGlobalOptions` interface.

src/lib/core/ripple/ripple.ts

@@ -23,7 +23,17 @@ import {RippleConfig, RippleRenderer} from './ripple-renderer';
 import {RippleRef} from './ripple-ref';
 
 export interface RippleGlobalOptions {
+  /**
+   * Whether ripples should be disabled. Ripples can be still launched manually by using
+   * the `launch()` method. Therefore focus indicators will still show up.
+   */
   disabled?: boolean;
+
+  /**
+   * If set, the default duration of the fade-in animation is divided by this value. For example,
+   * setting it to 0.5 will cause the ripple fade-in animation to take twice as long.
+   * A changed speedFactor will not affect the fade-out duration of the ripples.
+   */
   baseSpeedFactor?: number;
 }
 

tools/dgeni/common/dgeni-definitions.ts

@@ -0,0 +1,37 @@
+import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc';
+import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
+import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
+import {NormalizedMethodMemberDoc} from './normalize-method-parameters';
+
+/** Extended Dgeni class-like document that includes separated class members. */
+export interface CategorizedClassLikeDoc extends ClassLikeExportDoc {
+  methods: CategorizedMethodMemberDoc[];
+  properties: CategorizedPropertyMemberDoc[];
+  isDeprecated: boolean;
+}
+
+/** Extended Dgeni class document that includes extracted Angular metadata. */
+export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLikeDoc {
+  isDirective: boolean;
+  isService: boolean;
+  isNgModule: boolean;
+  directiveExportAs?: string | null;
+  directiveSelectors?: string[];
+  extendedDoc: ClassLikeExportDoc | null;
+}
+
+/** Extended Dgeni property-member document that includes extracted Angular metadata. */
+export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc {
+  description: string;
+  isDeprecated: boolean;
+  isDirectiveInput: boolean;
+  isDirectiveOutput: boolean;
+  directiveInputAlias: string;
+  directiveOutputAlias: string;
+}
+
+/** Extended Dgeni method-member document that simplifies logic for the Dgeni template. */
+export interface CategorizedMethodMemberDoc extends NormalizedMethodMemberDoc {
+  showReturns: boolean;
+  isDeprecated: boolean;
+}

tools/dgeni/common/sort-members.ts

@@ -1,5 +1,5 @@
-import {CategorizedMethodMemberDoc, CategorizedPropertyMemberDoc} from '../processors/categorizer';
 import {isDirectiveInput, isDirectiveOutput} from './decorators';
+import {CategorizedMethodMemberDoc, CategorizedPropertyMemberDoc} from './dgeni-definitions';
 
 /** Combined type for a categorized method member document. */
 type CategorizedMemberDoc = CategorizedMethodMemberDoc & CategorizedPropertyMemberDoc;

tools/dgeni/processors/categorizer.ts

@@ -1,10 +1,5 @@
-import {Processor, DocCollection} from 'dgeni';
-import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExportDoc';
-import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
-import {
-  NormalizedMethodMemberDoc,
-  normalizeMethodParameters
-} from '../common/normalize-method-parameters';
+import {DocCollection, Processor} from 'dgeni';
+import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
 import {
   decorateDeprecatedDoc,
   getDirectiveInputAlias,
@@ -19,35 +14,15 @@ import {
   isProperty,
   isService
 } from '../common/decorators';
-import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
-import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
+import {
+  CategorizedClassDoc,
+  CategorizedClassLikeDoc,
+  CategorizedMethodMemberDoc,
+  CategorizedPropertyMemberDoc
+} from '../common/dgeni-definitions';
+import {normalizeMethodParameters} from '../common/normalize-method-parameters';
 import {sortCategorizedMembers} from '../common/sort-members';
 
-export interface CategorizedClassDoc extends ClassExportDoc {
-  methods: CategorizedMethodMemberDoc[];
-  properties: CategorizedPropertyMemberDoc[];
-  isDirective: boolean;
-  isService: boolean;
-  isNgModule: boolean;
-  isDeprecated: boolean;
-  directiveExportAs?: string | null;
-  directiveSelectors?: string[];
-  extendedDoc: ClassLikeExportDoc | null;
-}
-
-export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc {
-  description: string;
-  isDeprecated: boolean;
-  isDirectiveInput: boolean;
-  isDirectiveOutput: boolean;
-  directiveInputAlias: string;
-  directiveOutputAlias: string;
-}
-
-export interface CategorizedMethodMemberDoc extends NormalizedMethodMemberDoc {
-  showReturns: boolean;
-  isDeprecated: boolean;
-}
 
 /**
  * Processor to add properties to docs objects.
@@ -62,34 +37,47 @@ export class Categorizer implements Processor {
   $runBefore = ['docs-processed'];
 
   $process(docs: DocCollection) {
-    docs.filter(doc => doc.docType === 'class').forEach(doc => this.decorateClassDoc(doc));
+    docs
+      .filter(doc => doc.docType === 'class' || doc.docType === 'interface')
+      .forEach(doc => this.decorateClassLikeDoc(doc));
   }
 
   /**
-   * Decorates all class docs inside of the dgeni pipeline.
-   * - Methods and properties of a class-doc will be extracted into separate variables.
-   * - Identifies directives, services or NgModules and marks them them in class-doc.
+   * Decorates all class and interface docs inside of the dgeni pipeline.
+   * - Members of a class and interface document will be extracted into separate variables.
    */
-  private decorateClassDoc(classDoc: CategorizedClassDoc) {
+  private decorateClassLikeDoc(classLikeDoc: CategorizedClassLikeDoc) {
     // Resolve all methods and properties from the classDoc.
-    classDoc.methods = classDoc.members
+    classLikeDoc.methods = classLikeDoc.members
       .filter(isMethod)
       .filter(filterDuplicateMembers) as CategorizedMethodMemberDoc[];
 
-    classDoc.properties = classDoc.members
+    classLikeDoc.properties = classLikeDoc.members
       .filter(isProperty)
       .filter(filterDuplicateMembers) as CategorizedPropertyMemberDoc[];
 
     // Call decorate hooks that can modify the method and property docs.
-    classDoc.methods.forEach(doc => this.decorateMethodDoc(doc));
-    classDoc.properties.forEach(doc => this.decoratePropertyDoc(doc));
+    classLikeDoc.methods.forEach(doc => this.decorateMethodDoc(doc));
+    classLikeDoc.properties.forEach(doc => this.decoratePropertyDoc(doc));
 
-    decorateDeprecatedDoc(classDoc);
+    decorateDeprecatedDoc(classLikeDoc);
 
     // Sort members
-    classDoc.methods.sort(sortCategorizedMembers);
-    classDoc.properties.sort(sortCategorizedMembers);
+    classLikeDoc.methods.sort(sortCategorizedMembers);
+    classLikeDoc.properties.sort(sortCategorizedMembers);
 
+    // Special decorations for real class documents that don't apply for interfaces.
+    if (classLikeDoc.docType === 'class') {
+      this.decorateClassDoc(classLikeDoc as CategorizedClassDoc);
+    }
+  }
+
+  /**
+   * Decorates all Dgeni class documents for a simpler use inside of the template.
+   * - Identifies directives, services or NgModules and marks them them inside of the doc.
+   * - Links the Dgeni document to the Dgeni document that the current class extends from.
+   */
+  private decorateClassDoc(classDoc: CategorizedClassDoc) {
     // Classes can only extend a single class. This means that there can't be multiple extend
     // clauses for the Dgeni document. To make the template syntax simpler and more readable,
     // store the extended class in a variable.

tools/dgeni/processors/component-grouper.ts

@@ -1,10 +1,14 @@
-import {CategorizedClassDoc} from './categorizer';
 import {DocCollection, Document, Processor} from 'dgeni';
+import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/InterfaceExportDoc';
 import * as path from 'path';
+import {CategorizedClassDoc} from '../common/dgeni-definitions';
 
 /** Component group data structure. */
 export class ComponentGroup {
 
+  /** Unique document type for Dgeni. */
+  docType = 'componentGroup';
+
   /** Name of the component group. */
   name: string;
 
@@ -24,32 +28,26 @@ export class ComponentGroup {
   id: string;
 
   /** Known aliases for the component group. */
-  aliases: string[];
-
-  /** Unique document type for Dgeni. */
-  docType: string;
+  aliases: string[] = [];
 
   /** List of categorized class docs that are defining a directive. */
-  directives: CategorizedClassDoc[];
+  directives: CategorizedClassDoc[] = [];
 
   /** List of categorized class docs that are defining a service. */
-  services: CategorizedClassDoc[];
+  services: CategorizedClassDoc[] = [];
 
   /** Additional classes that belong to the component group. */
-  additionalClasses: CategorizedClassDoc[];
+  additionalClasses: CategorizedClassDoc[] = [];
+
+  /** Additional interfaces that belong to the component group. */
+  additionalInterfaces: InterfaceExportDoc[] = [];
 
   /** NgModule that defines the current component group. */
-  ngModule: CategorizedClassDoc | null;
+  ngModule: CategorizedClassDoc | null = null;
 
   constructor(name: string) {
     this.name = name;
     this.id = `component-group-${name}`;
-    this.aliases = [];
-    this.docType = 'componentGroup';
-    this.directives = [];
-    this.services = [];
-    this.additionalClasses = [];
-    this.ngModule = null;
   }
 }
 
@@ -97,6 +95,8 @@ export class ComponentGrouper implements Processor {
         group.ngModule = doc;
       } else if (doc.docType == 'class') {
         group.additionalClasses.push(doc);
+      } else if (doc.docType == 'interface') {
+        group.additionalInterfaces.push(doc);
       }
     });
 

tools/dgeni/templates/componentGroup.template.html

@@ -19,6 +19,10 @@
   {% include 'class.template.html' %}
 {% endmacro %}
 
+{% macro interface(interface) -%}
+  {% include 'interface.template.html' %}
+{% endmacro %}
+
 <div class="docs-api">
   <h2>
     API reference for Angular {$ doc.packageDisplayName $} {$ doc.displayName $}
@@ -60,4 +64,14 @@
       {$ 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
+    </h3>
+    {% for item in doc.additionalInterfaces %}
+      {$ interface(item) $}
+    {% endfor %}
+  {%- endif -%}
 </div>

tools/dgeni/templates/interface.template.html

@@ -0,0 +1,16 @@
+<h4 id="{$ interface.name $}" class="docs-header-link docs-api-h4 docs-api-interface-name">
+  <span header-link="{$ interface.name $}"></span>
+  <code>{$ interface.name $}</code>
+</h4>
+
+{%- if interface.description -%}
+<p class="docs-api-interface-description">{$ interface.description | marked | safe $}</p>
+{%- endif -%}
+
+{%- if interface.isDeprecated -%}
+<div class="docs-api-interface-deprecated-marker">Deprecated</div>
+{%- endif -%}
+
+{$ propertyList(interface.properties) $}
+
+{$ methodList(interface.methods) $}