From 079d8e57d571b71ce6f8df81691a1e949a2cc890 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 29 Mar 2018 11:12:34 +0100 Subject: [PATCH] docs(common): migrate `@whatItDoes` tags to the description (#23062) We get the overview for the doc by splitting off the first paragraph. PR Close #23062 --- packages/common/src/directives/ng_class.ts | 4 ++-- packages/common/src/directives/ng_plural.ts | 10 ++++++---- packages/common/src/directives/ng_style.ts | 4 ++-- packages/common/src/directives/ng_switch.ts | 20 +++++++++---------- .../src/directives/ng_template_outlet.ts | 4 ++-- packages/common/src/i18n/format_date.ts | 3 ++- packages/common/src/i18n/format_number.ts | 7 +++---- .../src/location/hash_location_strategy.ts | 5 ++--- packages/common/src/location/location.ts | 4 +++- .../src/location/path_location_strategy.ts | 5 ++--- .../common/src/location/platform_location.ts | 5 +++-- packages/common/src/pipes/async_pipe.ts | 4 +++- packages/common/src/pipes/date_pipe.ts | 3 ++- .../common/src/pipes/deprecated/date_pipe.ts | 3 ++- .../src/pipes/deprecated/number_pipe.ts | 7 +++---- packages/common/src/pipes/i18n_plural_pipe.ts | 3 ++- packages/common/src/pipes/i18n_select_pipe.ts | 3 ++- packages/common/src/pipes/json_pipe.ts | 1 - packages/common/src/pipes/number_pipe.ts | 13 ++++++------ packages/common/src/pipes/slice_pipe.ts | 3 ++- 20 files changed, 58 insertions(+), 53 deletions(-) diff --git a/packages/common/src/directives/ng_class.ts b/packages/common/src/directives/ng_class.ts index d28cdbb4df..8df756eb8f 100644 --- a/packages/common/src/directives/ng_class.ts +++ b/packages/common/src/directives/ng_class.ts @@ -11,8 +11,6 @@ import {Directive, DoCheck, ElementRef, Input, IterableChanges, IterableDiffer, /** * @ngModule CommonModule * - * @whatItDoes Adds and removes CSS classes on an HTML element. - * * @usageNotes * ``` * ... @@ -28,6 +26,8 @@ import {Directive, DoCheck, ElementRef, Input, IterableChanges, IterableDiffer, * * @description * + * Adds and removes CSS classes on an HTML element. + * * The CSS classes are updated as follows, depending on the type of the expression evaluation: * - `string` - the CSS classes listed in the string (space delimited) are added, * - `Array` - the CSS classes declared as Array elements are added, diff --git a/packages/common/src/directives/ng_plural.ts b/packages/common/src/directives/ng_plural.ts index d8dfca4f06..cdf13c8374 100644 --- a/packages/common/src/directives/ng_plural.ts +++ b/packages/common/src/directives/ng_plural.ts @@ -16,8 +16,6 @@ import {SwitchView} from './ng_switch'; /** * @ngModule CommonModule * - * @whatItDoes Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization. - * * @usageNotes * ``` * @@ -29,6 +27,8 @@ import {SwitchView} from './ng_switch'; * * @description * + * Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization. + * * Displays DOM sub-trees that match the switch expression value, or failing that, DOM sub-trees * that match the switch expression's pluralization category. * @@ -83,8 +83,10 @@ export class NgPlural { /** * @ngModule CommonModule * - * @whatItDoes Creates a view that will be added/removed from the parent {@link NgPlural} when the - * given expression matches the plural expression according to CLDR rules. + * @description + * + * Creates a view that will be added/removed from the parent {@link NgPlural} when the + * given expression matches the plural expression according to CLDR rules. * * @usageNotes * ``` diff --git a/packages/common/src/directives/ng_style.ts b/packages/common/src/directives/ng_style.ts index 4f2f5a44a6..504021f7bc 100644 --- a/packages/common/src/directives/ng_style.ts +++ b/packages/common/src/directives/ng_style.ts @@ -11,8 +11,6 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer, /** * @ngModule CommonModule * - * @whatItDoes Update an HTML element styles. - * * @usageNotes * ``` * ... @@ -24,6 +22,8 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer, * * @description * + * Update an HTML element styles. + * * The styles are updated according to the value of the expression evaluation: * - keys are style names with an optional `.` suffix (ie 'top.px', 'font-style.em'), * - values are the values assigned to those properties (expressed in the given unit). diff --git a/packages/common/src/directives/ng_switch.ts b/packages/common/src/directives/ng_switch.ts index 44943c65b2..000e0ffbae 100644 --- a/packages/common/src/directives/ng_switch.ts +++ b/packages/common/src/directives/ng_switch.ts @@ -36,9 +36,6 @@ export class SwitchView { /** * @ngModule CommonModule * - * @whatItDoes Adds / removes DOM sub-trees when the nest match expressions matches the switch - * expression. - * * @usageNotes * ``` * @@ -55,6 +52,8 @@ export class SwitchView { * ``` * @description * + * Adds / removes DOM sub-trees when the nest match expressions matches the switch expression. + * * `NgSwitch` stamps out nested views when their match expression value matches the value of the * switch expression. * @@ -129,10 +128,6 @@ export class NgSwitch { /** * @ngModule CommonModule * - * @whatItDoes Creates a view that will be added/removed from the parent {@link NgSwitch} when the - * given expression evaluate to respectively the same/different value as the switch - * expression. - * * @usageNotes * ``` * @@ -141,6 +136,10 @@ export class NgSwitch { *``` * @description * + * Creates a view that will be added/removed from the parent {@link NgSwitch} when the + * given expression evaluate to respectively the same/different value as the switch + * expression. + * * Insert the sub-tree when the expression evaluates to the same value as the enclosing switch * expression. * @@ -169,10 +168,6 @@ export class NgSwitchCase implements DoCheck { /** * @ngModule CommonModule - * @whatItDoes Creates a view that is added to the parent {@link NgSwitch} when no case expressions - * match the - * switch expression. - * * @usageNotes * ``` * @@ -183,6 +178,9 @@ export class NgSwitchCase implements DoCheck { * * @description * + * Creates a view that is added to the parent {@link NgSwitch} when no case expressions + * match the switch expression. + * * Insert the sub-tree when no case expressions evaluate to the same value as the enclosing switch * expression. * diff --git a/packages/common/src/directives/ng_template_outlet.ts b/packages/common/src/directives/ng_template_outlet.ts index 641f4bf4d6..c76668ab14 100644 --- a/packages/common/src/directives/ng_template_outlet.ts +++ b/packages/common/src/directives/ng_template_outlet.ts @@ -11,8 +11,6 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange /** * @ngModule CommonModule * - * @whatItDoes Inserts an embedded view from a prepared `TemplateRef` - * * @usageNotes * ``` * @@ -20,6 +18,8 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange * * @description * + * Inserts an embedded view from a prepared `TemplateRef`. + * * You can attach a context object to the `EmbeddedViewRef` by setting `[ngTemplateOutletContext]`. * `[ngTemplateOutletContext]` should be an object, the object's keys will be available for binding * by the local template `let` declarations. diff --git a/packages/common/src/i18n/format_date.ts b/packages/common/src/i18n/format_date.ts index 981257ecb7..78015bf26f 100644 --- a/packages/common/src/i18n/format_date.ts +++ b/packages/common/src/i18n/format_date.ts @@ -42,9 +42,10 @@ enum TranslationType { /** * @ngModule CommonModule - * @whatItDoes Formats a date according to locale rules. * @description * + * Formats a date according to locale rules. + * * Where: * - `value` is a Date, a number (milliseconds since UTC epoch) or an ISO string * (https://www.w3.org/TR/NOTE-datetime). diff --git a/packages/common/src/i18n/format_number.ts b/packages/common/src/i18n/format_number.ts index 4f31086881..b2c4876141 100644 --- a/packages/common/src/i18n/format_number.ts +++ b/packages/common/src/i18n/format_number.ts @@ -124,9 +124,10 @@ function formatNumberToLocaleString( /** * @ngModule CommonModule - * @whatItDoes Formats a number as currency using locale rules. * @description * + * Formats a number as currency using locale rules. + * * Use `currency` to format a number as currency. * * Where: @@ -158,10 +159,9 @@ export function formatCurrency( /** * @ngModule CommonModule - * @whatItDoes Formats a number as a percentage according to locale rules. * @description * - * Formats a number as percentage. + * Formats a number as a percentage according to locale rules. * * Where: * - `value` is a number. @@ -181,7 +181,6 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string /** * @ngModule CommonModule - * @whatItDoes Formats a number according to locale rules. * @description * * Formats a number as text. Group sizing and separator and other locale-specific diff --git a/packages/common/src/location/hash_location_strategy.ts b/packages/common/src/location/hash_location_strategy.ts index 70bd23256e..1fe05f007e 100644 --- a/packages/common/src/location/hash_location_strategy.ts +++ b/packages/common/src/location/hash_location_strategy.ts @@ -16,10 +16,9 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; /** - * @whatItDoes Use URL hash for storing application location data. * @description - * `HashLocationStrategy` is a {@link LocationStrategy} used to configure the - * {@link Location} service to represent its state in the + * A {@link LocationStrategy} used to configure the {@link Location} service to + * represent its state in the * [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) * of the browser's URL. * diff --git a/packages/common/src/location/location.ts b/packages/common/src/location/location.ts index dfd07858a8..ce5a6d0f3e 100644 --- a/packages/common/src/location/location.ts +++ b/packages/common/src/location/location.ts @@ -20,8 +20,10 @@ export interface PopStateEvent { } /** - * @whatItDoes `Location` is a service that applications can use to interact with a browser's URL. * @description + * + * A service that applications can use to interact with a browser's URL. + * * Depending on which {@link LocationStrategy} is used, `Location` will either persist * to the URL's path or the URL's hash segment. * diff --git a/packages/common/src/location/path_location_strategy.ts b/packages/common/src/location/path_location_strategy.ts index d3ccf7ecfe..3854ec8bf0 100644 --- a/packages/common/src/location/path_location_strategy.ts +++ b/packages/common/src/location/path_location_strategy.ts @@ -16,10 +16,9 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; /** - * @whatItDoes Use URL for storing application location data. * @description - * `PathLocationStrategy` is a {@link LocationStrategy} used to configure the - * {@link Location} service to represent its state in the + * A {@link LocationStrategy} used to configure the {@link Location} service to + * represent its state in the * [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) of the * browser's URL. * diff --git a/packages/common/src/location/platform_location.ts b/packages/common/src/location/platform_location.ts index 177b6a474a..c222a3a75a 100644 --- a/packages/common/src/location/platform_location.ts +++ b/packages/common/src/location/platform_location.ts @@ -48,13 +48,14 @@ export abstract class PlatformLocation { } /** - * @whatItDoes indicates when a location is initialized + * @description Indicates when a location is initialized. * @experimental */ export const LOCATION_INITIALIZED = new InjectionToken>('Location Initialized'); /** - * A serializable version of the event from onPopState or onHashChange + * @description + * A serializable version of the event from `onPopState` or `onHashChange` * * @experimental */ diff --git a/packages/common/src/pipes/async_pipe.ts b/packages/common/src/pipes/async_pipe.ts index 108e90a1c1..1167ae7524 100644 --- a/packages/common/src/pipes/async_pipe.ts +++ b/packages/common/src/pipes/async_pipe.ts @@ -42,8 +42,10 @@ const _observableStrategy = new ObservableStrategy(); /** * @ngModule CommonModule - * @whatItDoes Unwraps a value from an asynchronous primitive. * @description + * + * Unwraps a value from an asynchronous primitive. + * * The `async` pipe subscribes to an `Observable` or `Promise` and returns the latest value it has * emitted. When a new value is emitted, the `async` pipe marks the component to be checked for * changes. When the component gets destroyed, the `async` pipe unsubscribes automatically to avoid diff --git a/packages/common/src/pipes/date_pipe.ts b/packages/common/src/pipes/date_pipe.ts index 0469530c7c..821b7dd0fe 100644 --- a/packages/common/src/pipes/date_pipe.ts +++ b/packages/common/src/pipes/date_pipe.ts @@ -13,9 +13,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; // clang-format off /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatDate} to format a date according to locale rules. * @description * + * Uses the function {@link formatDate} to format a date according to locale rules. + * * Where: * - `value` is a date object or a number (milliseconds since UTC epoch) or an ISO string * (https://www.w3.org/TR/NOTE-datetime). diff --git a/packages/common/src/pipes/deprecated/date_pipe.ts b/packages/common/src/pipes/deprecated/date_pipe.ts index 38c990ea37..d098773632 100644 --- a/packages/common/src/pipes/deprecated/date_pipe.ts +++ b/packages/common/src/pipes/deprecated/date_pipe.ts @@ -13,9 +13,10 @@ import {DateFormatter} from './intl'; /** * @ngModule CommonModule - * @whatItDoes Formats a date according to locale rules. * @description * + * Formats a date according to locale rules. + * * Where: * - `expression` is a date object or a number (milliseconds since UTC epoch) or an ISO string * (https://www.w3.org/TR/NOTE-datetime). diff --git a/packages/common/src/pipes/deprecated/number_pipe.ts b/packages/common/src/pipes/deprecated/number_pipe.ts index f87991ff93..fb703ea416 100644 --- a/packages/common/src/pipes/deprecated/number_pipe.ts +++ b/packages/common/src/pipes/deprecated/number_pipe.ts @@ -61,7 +61,6 @@ function formatNumber( /** * @ngModule CommonModule - * @whatItDoes Formats a number according to locale rules. * * Formats a number as text. Group sizing and separator and other locale-specific * configurations are based on the active locale. @@ -97,11 +96,10 @@ export class DeprecatedDecimalPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Formats a number as a percentage according to locale rules. * * @description * - * Formats a number as percentage. + * Formats a number as percentage according to locale rules. * * - `digitInfo` See {@link DecimalPipe} for detailed description. * @@ -126,9 +124,10 @@ export class DeprecatedPercentPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Formats a number as currency using locale rules. * @description * + * Formats a number as currency using locale rules. + * * Use `currency` to format a number as currency. * * - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such diff --git a/packages/common/src/pipes/i18n_plural_pipe.ts b/packages/common/src/pipes/i18n_plural_pipe.ts index e7f904102e..80d08d4492 100644 --- a/packages/common/src/pipes/i18n_plural_pipe.ts +++ b/packages/common/src/pipes/i18n_plural_pipe.ts @@ -14,9 +14,10 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; /** * @ngModule CommonModule - * @whatItDoes Maps a value to a string that pluralizes the value according to locale rules. * @description * + * Maps a value to a string that pluralizes the value according to locale rules. + * * Where: * - `expression` is a number. * - `mapping` is an object that mimics the ICU format, see diff --git a/packages/common/src/pipes/i18n_select_pipe.ts b/packages/common/src/pipes/i18n_select_pipe.ts index 91f9d96ee6..2ab7449b29 100644 --- a/packages/common/src/pipes/i18n_select_pipe.ts +++ b/packages/common/src/pipes/i18n_select_pipe.ts @@ -11,9 +11,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Generic selector that displays the string that matches the current value. * @description * + * Generic selector that displays the string that matches the current value. + * * Where `mapping` is an object that indicates the text that should be displayed * for different values of the provided `expression`. * If none of the keys of the mapping match the value of the `expression`, then the content diff --git a/packages/common/src/pipes/json_pipe.ts b/packages/common/src/pipes/json_pipe.ts index ed072c9ff1..f0801164a9 100644 --- a/packages/common/src/pipes/json_pipe.ts +++ b/packages/common/src/pipes/json_pipe.ts @@ -10,7 +10,6 @@ import {Pipe, PipeTransform} from '@angular/core'; /** * @ngModule CommonModule - * @whatItDoes Converts value into JSON string. * @description * * Converts value into string using `JSON.stringify`. Useful for debugging. diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 11f9b0f644..e9b47d49aa 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -13,9 +13,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatNumber} to format a number according to locale rules. * @description * + * Uses the function {@link formatNumber} to format a number according to locale rules. + * * Formats a number as text. Group sizing and separator and other locale-specific * configurations are based on the locale. * @@ -55,11 +56,10 @@ export class DecimalPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatPercent} to format a number as a percentage according - * to locale rules. * @description * - * Formats a number as percentage. + * Uses the function {@link formatPercent} to format a number as a percentage according + * to locale rules. * * Where: * - `value` is a number. @@ -93,11 +93,10 @@ export class PercentPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a - * number as currency using locale rules. * @description * - * Use `currency` to format a number as currency. + * Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a + * number as currency using locale rules. * * Where: * - `value` is a number. diff --git a/packages/common/src/pipes/slice_pipe.ts b/packages/common/src/pipes/slice_pipe.ts index 06549f0ff0..c0780866ca 100644 --- a/packages/common/src/pipes/slice_pipe.ts +++ b/packages/common/src/pipes/slice_pipe.ts @@ -11,9 +11,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Creates a new List or String containing a subset (slice) of the elements. * @description * + * Creates a new List or String containing a subset (slice) of the elements. + * * Where the input expression is a `List` or `String`, and: * - `start`: The starting index of the subset to return. * - **a positive integer**: return the item at `start` index and all items after