diff --git a/src/cdk/collections/selection.ts b/src/cdk/collections/selection.ts index d159b2b11b9..160f344b1c7 100644 --- a/src/cdk/collections/selection.ts +++ b/src/cdk/collections/selection.ts @@ -202,6 +202,7 @@ export interface SelectionChange { /** * 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.'); diff --git a/src/cdk/table/can-stick.ts b/src/cdk/table/can-stick.ts index 41775e48a5e..bbabd43658a 100644 --- a/src/cdk/table/can-stick.ts +++ b/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>(base: T): Constructor & T { diff --git a/src/lib/autocomplete/autocomplete-trigger.ts b/src/lib/autocomplete/autocomplete-trigger.ts index e7aa0600b40..c7b01c8f07c 100644 --- a/src/lib/autocomplete/autocomplete-trigger.ts +++ b/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`. ' + diff --git a/src/lib/sidenav/drawer.ts b/src/lib/sidenav/drawer.ts index 5c9588748b0..eaf996eef1d 100644 --- a/src/lib/sidenav/drawer.ts +++ b/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}"'`); } diff --git a/src/lib/tooltip/tooltip.ts b/src/lib/tooltip/tooltip.ts index c059be30d6f..b7a8b26a142 100644 --- a/src/lib/tooltip/tooltip.ts +++ b/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, diff --git a/tools/dgeni/common/dgeni-definitions.ts b/tools/dgeni/common/dgeni-definitions.ts index 363b719677b..8d9737b5a7f 100644 --- a/tools/dgeni/common/dgeni-definitions.ts +++ b/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 {} diff --git a/tools/dgeni/common/normalize-method-parameters.ts b/tools/dgeni/common/normalize-function-parameters.ts similarity index 62% rename from tools/dgeni/common/normalize-method-parameters.ts rename to tools/dgeni/common/normalize-function-parameters.ts index 73bb92c99a9..1a963dce35c 100644 --- a/tools/dgeni/common/normalize-method-parameters.ts +++ b/tools/dgeni/common/normalize-function-parameters.ts @@ -1,11 +1,14 @@ -import {MethodMemberDoc} from 'dgeni-packages/typescript/api-doc-types/MethodMemberDoc'; +import { + ParameterContainer, + ParamTag, +} from 'dgeni-packages/typescript/api-doc-types/ParameterContainer'; +import {ApiDoc} from 'dgeni-packages/typescript/api-doc-types/ApiDoc'; -export class NormalizedMethodMemberDoc extends MethodMemberDoc { - params?: MethodParameterInfo[]; +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(); diff --git a/tools/dgeni/processors/categorizer.ts b/tools/dgeni/processors/categorizer.ts index 4554988bcc5..1c1f7fe4920 100644 --- a/tools/dgeni/processors/categorizer.ts +++ b/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); } /** diff --git a/tools/dgeni/processors/component-grouper.ts b/tools/dgeni/processors/component-grouper.ts index f80799e1d4f..e584b3906dd 100644 --- a/tools/dgeni/processors/component-grouper.ts +++ b/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); } }); diff --git a/tools/dgeni/templates/componentGroup.template.html b/tools/dgeni/templates/componentGroup.template.html index 3dc381419d2..6eeefbec39b 100644 --- a/tools/dgeni/templates/componentGroup.template.html +++ b/tools/dgeni/templates/componentGroup.template.html @@ -79,6 +79,20 @@ {% endfor %} {%- endif -%} + {%- if doc.additionalFunctions.length -%} + + {% 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 -%}