docs: show exported functions (#12736)

Changes the Dgeni setup to properly display exported functions (e.g. from cdk/coercion, cdk/a11y, cdk/platform)

Author: devversion

src/cdk/collections/selection.ts

@@ -202,6 +202,7 @@ export interface SelectionChange<T> {
 /**
  * Returns an error that reports that multiple values are passed into a selection model
  * with a single value.
+ * @docs-private
  */
 export function getMultipleValuesInSingleSelectionError() {
   return Error('Cannot pass multiple values into SelectionModel with single-value mode.');

src/cdk/table/can-stick.ts

@@ -35,6 +35,7 @@ export interface CanStick {
  * Mixin to provide a directive with a function that checks if the sticky input has been
  * changed since the last time the function was called. Essentially adds a dirty-check to the
  * sticky value.
+ * @docs-private
  */
 export function mixinHasStickyInput<T extends Constructor<{}>>(base: T):
     Constructor<CanStick> & T {

src/lib/autocomplete/autocomplete-trigger.ts

@@ -87,6 +87,7 @@ export const MAT_AUTOCOMPLETE_VALUE_ACCESSOR: any = {
 
 /**
  * Creates an error to be thrown when attempting to use an autocomplete trigger without a panel.
+ * @docs-private
  */
 export function getMatAutocompleteMissingPanelError(): Error {
   return Error('Attempting to open an undefined instance of `mat-autocomplete`. ' +

src/lib/sidenav/drawer.ts

@@ -42,7 +42,10 @@ import {matDrawerAnimations} from './drawer-animations';
 import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
 
 
-/** Throws an exception when two MatDrawer are matching the same position. */
+/**
+ * Throws an exception when two MatDrawer are matching the same position.
+ * @docs-private
+ */
 export function throwMatDuplicatedDrawerError(position: string) {
   throw Error(`A drawer was already declared for 'position="${position}"'`);
 }

src/lib/tooltip/tooltip.ts

@@ -52,7 +52,10 @@ export const SCROLL_THROTTLE_MS = 20;
 /** CSS class that will be attached to the overlay panel. */
 export const TOOLTIP_PANEL_CLASS = 'mat-tooltip-panel';
 
-/** Creates an error to be thrown if the user supplied an invalid tooltip position. */
+/**
+ * Creates an error to be thrown if the user supplied an invalid tooltip position.
+ * @docs-private
+ */
 export function getMatTooltipInvalidPositionError(position: string) {
   return Error(`Tooltip position "${position}" is invalid.`);
 }
@@ -87,6 +90,7 @@ export const MAT_TOOLTIP_DEFAULT_OPTIONS =
       factory: MAT_TOOLTIP_DEFAULT_OPTIONS_FACTORY
     });
 
+/** @docs-private */
 export function MAT_TOOLTIP_DEFAULT_OPTIONS_FACTORY(): MatTooltipDefaultOptions {
   return {
     showDelay: 0,

tools/dgeni/common/dgeni-definitions.ts

@@ -3,7 +3,9 @@ import {ClassExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassExpor
 import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
 import {PropertyMemberDoc} from 'dgeni-packages/typescript/api-doc-types/PropertyMemberDoc';
 import {ParsedDecorator} from 'dgeni-packages/typescript/services/TsParser/getDecorators';
-import {NormalizedMethodMemberDoc} from './normalize-method-parameters';
+import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc';
+import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
+import {NormalizedFunctionDoc} from './normalize-function-parameters';
 
 /** Interface that describes categorized docs that can be deprecated. */
 export interface DeprecationDoc extends ApiDoc {
@@ -43,6 +45,9 @@ export interface CategorizedPropertyMemberDoc extends PropertyMemberDoc, Depreca
 }
 
 /** Extended Dgeni method-member document that simplifies logic for the Dgeni template. */
-export interface CategorizedMethodMemberDoc extends NormalizedMethodMemberDoc, DeprecationDoc {
-  showReturns: boolean;
-}
+export interface CategorizedMethodMemberDoc
+    extends NormalizedFunctionDoc, MethodMemberDoc, DeprecationDoc {}
+
+/** Extended Dgeni function export document that simplifies logic for the Dgeni template. */
+export interface CategorizedFunctionExportDoc
+    extends NormalizedFunctionDoc, FunctionExportDoc, DeprecationDoc {}

tools/dgeni/common/normalize-method-parameters.ts renamed to tools/dgeni/common/normalize-function-parameters.ts

@@ -1,11 +1,14 @@
-import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
-
-export class NormalizedMethodMemberDoc extends MethodMemberDoc {
-  params?: MethodParameterInfo[];
+import {
+  ParameterContainer,
+  ParamTag,
+} from 'dgeni-packages/typescript/api-doc-types/ParameterContainer';
+import {ApiDoc} from 'dgeni-packages/typescript/api-doc-types/ApiDoc';
+
+export interface NormalizedFunctionDoc extends ParameterContainer, ApiDoc {
+  params?: FunctionParameterInfo[];
 }
 
-export interface MethodParameterInfo {
-  name: string;
+export interface FunctionParameterInfo extends ParamTag {
   type: string;
   isOptional: boolean;
 }
@@ -20,9 +23,9 @@ export interface MethodParameterInfo {
  * We will use the `params` property to store the final normalized form since it is already
  * an object.
  */
-export function normalizeMethodParameters(method: NormalizedMethodMemberDoc) {
-  if (method.parameters) {
-    method.parameters.forEach(parameter => {
+export function normalizeFunctionParameters(doc: NormalizedFunctionDoc) {
+  if (doc.parameters) {
+    doc.parameters.forEach(parameter => {
       let [parameterName, parameterType] = parameter.split(':');
 
       // If the parameter is optional, the name here will contain a '?'. We store whether the
@@ -33,23 +36,22 @@ export function normalizeMethodParameters(method: NormalizedMethodMemberDoc) {
         parameterName = parameterName.replace('?', '');
       }
 
-      if (!method.params) {
-        method.params = [];
-      }
+      doc.params = doc.params || [];
 
       if (!parameterType) {
         console.warn(`Missing parameter type information (${parameterName}) in ` +
-          `${method.fileInfo.relativePath}:${method.startingLine}`);
+          `${doc.fileInfo.relativePath}:${doc.startingLine}`);
         return;
       }
 
-      const existingParameterInfo = method.params.find(p => p.name == parameterName);
+      const existingParameterInfo = doc.params.find(p => p.name == parameterName);
 
       if (!existingParameterInfo) {
-        method.params.push({
+        doc.params.push({
           name: parameterName,
           type: parameterType.trim(),
-          isOptional: isOptional
+          isOptional: isOptional,
+          description: ''
         });
       } else {
         existingParameterInfo.type = parameterType.trim();

tools/dgeni/processors/categorizer.ts

@@ -1,15 +1,23 @@
 import {DocCollection, Processor} from 'dgeni';
 import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc';
-import {getDirectiveMetadata} from '../common/directive-metadata';
 import {
-  decorateDeprecatedDoc, getDirectiveSelectors, isDirective, isMethod, isNgModule, isProperty,
-  isService
+  decorateDeprecatedDoc,
+  getDirectiveSelectors,
+  isDirective,
+  isMethod,
+  isNgModule,
+  isProperty,
+  isService,
 } from '../common/decorators';
 import {
-  CategorizedClassDoc, CategorizedClassLikeDoc, CategorizedMethodMemberDoc,
-  CategorizedPropertyMemberDoc
+  CategorizedClassDoc,
+  CategorizedClassLikeDoc,
+  CategorizedFunctionExportDoc,
+  CategorizedMethodMemberDoc,
+  CategorizedPropertyMemberDoc,
 } from '../common/dgeni-definitions';
-import {normalizeMethodParameters} from '../common/normalize-method-parameters';
+import {getDirectiveMetadata} from '../common/directive-metadata';
+import {normalizeFunctionParameters} from '../common/normalize-function-parameters';
 import {getInputBindingData, getOutputBindingData} from '../common/property-bindings';
 import {sortCategorizedMembers} from '../common/sort-members';
 
@@ -30,6 +38,10 @@ export class Categorizer implements Processor {
     docs
       .filter(doc => doc.docType === 'class' || doc.docType === 'interface')
       .forEach(doc => this.decorateClassLikeDoc(doc));
+
+    docs
+      .filter(doc => doc.docType === 'function')
+      .forEach(doc => this.decorateFunctionExportDoc(doc));
   }
 
   /**
@@ -92,11 +104,17 @@ export class Categorizer implements Processor {
    * will be normalized, so that they can be easily used inside of dgeni templates.
    */
   private decorateMethodDoc(methodDoc: CategorizedMethodMemberDoc) {
-    normalizeMethodParameters(methodDoc);
+    normalizeFunctionParameters(methodDoc);
     decorateDeprecatedDoc(methodDoc);
+  }
 
-    // Mark methods with a `void` return type so we can omit show the return type in the docs.
-    methodDoc.showReturns = methodDoc.type ? methodDoc.type !== 'void' : false;
+  /**
+   * Method that will be called for each function export doc. The parameters for the functions
+   * will be normalized, so that they can be easily used inside of Dgeni templates.
+   */
+  private decorateFunctionExportDoc(functionDoc: CategorizedFunctionExportDoc) {
+    normalizeFunctionParameters(functionDoc);
+    decorateDeprecatedDoc(functionDoc);
   }
 
   /**

tools/dgeni/processors/component-grouper.ts

@@ -1,6 +1,7 @@
 import {DocCollection, Document, Processor} from 'dgeni';
 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';
 
@@ -46,6 +47,9 @@ export class ComponentGroup {
   /** Additional type aliases that belong to the component group. */
   additionalTypeAliases: TypeAliasExportDoc[] = [];
 
+  /** Additional functions that belong to the component group. */
+  additionalFunctions: FunctionExportDoc[] = [];
+
   /** NgModule that defines the current component group. */
   ngModule: CategorizedClassDoc | null = null;
 
@@ -103,6 +107,8 @@ export class ComponentGrouper implements Processor {
         group.additionalInterfaces.push(doc);
       } else if (doc.docType === 'type-alias') {
         group.additionalTypeAliases.push(doc);
+      } else if (doc.docType === 'function') {
+        group.additionalFunctions.push(doc);
       }
     });
 

tools/dgeni/templates/componentGroup.template.html

@@ -79,6 +79,20 @@ <h3 id="additional_interfaces" class="docs-header-link docs-api-h3">
     {% 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
+    </h3>
+    {% for item in doc.additionalFunctions %}
+      {#
+        Since the function docs have a similar structure as method docs, we use
+        the method template.
+      #}
+      {$ method(item) $}
+    {% 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>

tools/dgeni/templates/method.template.html

@@ -47,7 +47,7 @@
   {% endfor %}
   {%- endif -%}
 
-  {%- if method.showReturns -%}
+  {%- if method.type and method.type !== "void" -%}
   <thead>
     <tr class="docs-api-method-returns-header-row">
       <th colspan="2" class="docs-api-method-returns-header-cell">Returns</th>