From 5069c069067e27f5cfb876b62064d9e6381fe6d0 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 3 May 2018 09:38:05 +0100 Subject: [PATCH] docs(common): fix content errors (#23667) PR Close #23667 --- .../common/src/directives/ng_component_outlet.ts | 5 ++++- packages/common/src/directives/ng_for_of.ts | 2 ++ packages/common/src/directives/ng_if.ts | 11 +++++++---- .../common/src/directives/ng_template_outlet.ts | 15 +++++++-------- .../common/src/location/hash_location_strategy.ts | 2 ++ packages/common/src/location/location.ts | 5 ++++- packages/common/src/location/location_strategy.ts | 2 ++ .../common/src/location/path_location_strategy.ts | 2 ++ packages/common/src/pipes/async_pipe.ts | 4 ++-- packages/common/src/pipes/deprecated/date_pipe.ts | 2 ++ .../common/src/pipes/deprecated/number_pipe.ts | 7 ++++++- packages/common/src/pipes/i18n_plural_pipe.ts | 4 +++- packages/common/src/pipes/i18n_select_pipe.ts | 4 +++- packages/common/src/pipes/json_pipe.ts | 3 +-- packages/common/src/pipes/number_pipe.ts | 9 ++++----- packages/common/src/pipes/slice_pipe.ts | 11 +++++++---- 16 files changed, 58 insertions(+), 30 deletions(-) diff --git a/packages/common/src/directives/ng_component_outlet.ts b/packages/common/src/directives/ng_component_outlet.ts index 8048cafc95..3d04a2574e 100644 --- a/packages/common/src/directives/ng_component_outlet.ts +++ b/packages/common/src/directives/ng_component_outlet.ts @@ -16,6 +16,8 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo * `NgComponentOutlet` requires a component type, if a falsy value is set the view will clear and * any existing component will get destroyed. * + * @usageNotes + * * ### Fine tune control * * You can control the component creation process by using the following optional attributes: @@ -50,7 +52,8 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo * ngModuleFactory: moduleFactory;"> * * ``` - * ## Example + * + * ### A simple example * * {@example common/ngComponentOutlet/ts/module.ts region='SimpleExample'} * diff --git a/packages/common/src/directives/ng_for_of.ts b/packages/common/src/directives/ng_for_of.ts index 89cb9c1b2e..0779162ddb 100644 --- a/packages/common/src/directives/ng_for_of.ts +++ b/packages/common/src/directives/ng_for_of.ts @@ -27,6 +27,8 @@ export class NgForOfContext { * for each instantiated template inherits from the outer context with the given loop variable * set to the current item from the iterable. * + * @usageNotes + * * ### Local Variables * * `NgForOf` provides several exported values that can be aliased to local variables: diff --git a/packages/common/src/directives/ng_if.ts b/packages/common/src/directives/ng_if.ts index 9bcab1d949..4c8d42f26c 100644 --- a/packages/common/src/directives/ng_if.ts +++ b/packages/common/src/directives/ng_if.ts @@ -17,13 +17,16 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri * - `then` template is the inline template of `ngIf` unless bound to a different value. * - `else` template is blank unless it is bound. * - * ## Most common usage + * + * @usageNotes + * + * ### Most common usage * * The most common usage of the `ngIf` directive is to conditionally show the inline template as * seen in this example: * {@example common/ngIf/ts/module.ts region='NgIfSimple'} * - * ## Showing an alternative template using `else` + * ### Showing an alternative template using `else` * * If it is necessary to display a template when the `expression` is falsy use the `else` template * binding as shown. Note that the `else` binding points to a `` labeled `#elseBlock`. @@ -32,7 +35,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri * * {@example common/ngIf/ts/module.ts region='NgIfElse'} * - * ## Using non-inlined `then` template + * ### Using non-inlined `then` template * * Usually the `then` template is the inlined template of the `ngIf`, but it can be changed using * a binding (just like `else`). Because `then` and `else` are bindings, the template references can @@ -40,7 +43,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri * * {@example common/ngIf/ts/module.ts region='NgIfThenElse'} * - * ## Storing conditional result in a variable + * ### Storing conditional result in a variable * * A common pattern is that we need to show a set of properties from the same object. If the * object is undefined, then we have to use the safe-traversal-operator `?.` to guard against diff --git a/packages/common/src/directives/ng_template_outlet.ts b/packages/common/src/directives/ng_template_outlet.ts index d2feb77534..2ff09b3807 100644 --- a/packages/common/src/directives/ng_template_outlet.ts +++ b/packages/common/src/directives/ng_template_outlet.ts @@ -11,11 +11,6 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange /** * @ngModule CommonModule * - * @usageNotes - * ``` - * - * ``` - * * @description * * Inserts an embedded view from a prepared `TemplateRef`. @@ -24,13 +19,17 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange * `[ngTemplateOutletContext]` should be an object, the object's keys will be available for binding * by the local template `let` declarations. * - * Note: using the key `$implicit` in the context object will set its value as default. + * @usageNotes + * ``` + * + * ``` * - * ## Example + * Using the key `$implicit` in the context object will set its value as default. + * + * ### Example * * {@example common/ngTemplateOutlet/ts/module.ts region='NgTemplateOutlet'} * - * */ @Directive({selector: '[ngTemplateOutlet]'}) export class NgTemplateOutlet implements OnChanges { diff --git a/packages/common/src/location/hash_location_strategy.ts b/packages/common/src/location/hash_location_strategy.ts index 64a1f5733f..d52c4c7610 100644 --- a/packages/common/src/location/hash_location_strategy.ts +++ b/packages/common/src/location/hash_location_strategy.ts @@ -25,6 +25,8 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; * For instance, if you call `location.go('/foo')`, the browser's URL will become * `example.com#/foo`. * + * @usageNotes + * * ### Example * * {@example common/location/ts/hash_location_component.ts region='LocationComponent'} diff --git a/packages/common/src/location/location.ts b/packages/common/src/location/location.ts index ec329172b8..4ee84dfb6b 100644 --- a/packages/common/src/location/location.ts +++ b/packages/common/src/location/location.ts @@ -27,7 +27,9 @@ export interface PopStateEvent { * Depending on which {@link LocationStrategy} is used, `Location` will either persist * to the URL's path or the URL's hash segment. * - * Note: it's better to use {@link Router#navigate} service to trigger route changes. Use + * @usageNotes + * + * It's better to use {@link Router#navigate} service to trigger route changes. Use * `Location` only if you need to interact with or create normalized URLs outside of * routing. * @@ -39,6 +41,7 @@ export interface PopStateEvent { * - `/my/app/user/123/` **is not** normalized * * ### Example + * * {@example common/location/ts/path_location_component.ts region='LocationComponent'} * */ diff --git a/packages/common/src/location/location_strategy.ts b/packages/common/src/location/location_strategy.ts index 8284c20b86..d40e0e2452 100644 --- a/packages/common/src/location/location_strategy.ts +++ b/packages/common/src/location/location_strategy.ts @@ -47,6 +47,8 @@ export abstract class LocationStrategy { * representing the URL prefix that should be preserved when generating and recognizing * URLs. * + * @usageNotes + * * ### Example * * ```typescript diff --git a/packages/common/src/location/path_location_strategy.ts b/packages/common/src/location/path_location_strategy.ts index 42161382d6..e47932568c 100644 --- a/packages/common/src/location/path_location_strategy.ts +++ b/packages/common/src/location/path_location_strategy.ts @@ -34,6 +34,8 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; * `location.go('/foo')`, the browser's URL will become * `example.com/my/app/foo`. * + * @usageNotes + * * ### Example * * {@example common/location/ts/path_location_component.ts region='LocationComponent'} diff --git a/packages/common/src/pipes/async_pipe.ts b/packages/common/src/pipes/async_pipe.ts index 9f08ee63cd..244f5b8d7e 100644 --- a/packages/common/src/pipes/async_pipe.ts +++ b/packages/common/src/pipes/async_pipe.ts @@ -51,8 +51,9 @@ const _observableStrategy = new ObservableStrategy(); * changes. When the component gets destroyed, the `async` pipe unsubscribes automatically to avoid * potential memory leaks. * + * @usageNotes * - * ## Examples + * ### Examples * * This example binds a `Promise` to the view. Clicking the `Resolve` button resolves the * promise. @@ -64,7 +65,6 @@ const _observableStrategy = new ObservableStrategy(); * * {@example common/pipes/ts/async_pipe.ts region='AsyncPipeObservable'} * - * */ @Pipe({name: 'async', pure: false}) export class AsyncPipe implements OnDestroy, PipeTransform { diff --git a/packages/common/src/pipes/deprecated/date_pipe.ts b/packages/common/src/pipes/deprecated/date_pipe.ts index 98db1e3e3d..c4379fb667 100644 --- a/packages/common/src/pipes/deprecated/date_pipe.ts +++ b/packages/common/src/pipes/deprecated/date_pipe.ts @@ -64,6 +64,8 @@ import {DateFormatter} from './intl'; * - this pipe uses the Internationalization API. Therefore it is only reliable in Chrome and Opera * browsers. * + * @usageNotes + * * ### Examples * * Assuming `dateObj` is (year: 2010, month: 9, day: 3, hour: 12 PM, minute: 05, second: 08) diff --git a/packages/common/src/pipes/deprecated/number_pipe.ts b/packages/common/src/pipes/deprecated/number_pipe.ts index 8af1efe6d0..6195edffcc 100644 --- a/packages/common/src/pipes/deprecated/number_pipe.ts +++ b/packages/common/src/pipes/deprecated/number_pipe.ts @@ -78,11 +78,12 @@ function formatNumber( * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers * and may require a polyfill. See [Browser Support](guide/browser-support) for details. * + * @usageNotes + * * ### Example * * {@example common/pipes/ts/number_pipe.ts region='DeprecatedNumberPipe'} * - * */ @Pipe({name: 'number'}) export class DeprecatedDecimalPipe implements PipeTransform { @@ -106,6 +107,8 @@ export class DeprecatedDecimalPipe implements PipeTransform { * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers * and may require a polyfill. See [Browser Support](guide/browser-support) for details. * + * @usageNotes + * * ### Example * * {@example common/pipes/ts/percent_pipe.ts region='DeprecatedPercentPipe'} @@ -140,6 +143,8 @@ export class DeprecatedPercentPipe implements PipeTransform { * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers * and may require a polyfill. See [Browser Support](guide/browser-support) for details. * + * @usageNotes + * * ### Example * * {@example common/pipes/ts/currency_pipe.ts region='DeprecatedCurrencyPipe'} diff --git a/packages/common/src/pipes/i18n_plural_pipe.ts b/packages/common/src/pipes/i18n_plural_pipe.ts index 2ed3eb5138..5ecdf3d5f7 100644 --- a/packages/common/src/pipes/i18n_plural_pipe.ts +++ b/packages/common/src/pipes/i18n_plural_pipe.ts @@ -18,7 +18,9 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; * * Maps a value to a string that pluralizes the value according to locale rules. * - * ## Example + * @usageNotes + * + * ### Example * * {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'} * diff --git a/packages/common/src/pipes/i18n_select_pipe.ts b/packages/common/src/pipes/i18n_select_pipe.ts index 0ff8460d01..c276f99924 100644 --- a/packages/common/src/pipes/i18n_select_pipe.ts +++ b/packages/common/src/pipes/i18n_select_pipe.ts @@ -18,7 +18,9 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * If none of the keys of the `mapping` match the `value`, then the content * of the `other` key is returned when present, otherwise an empty string is returned. * - * ## Example + * @usageNotes + * + * ### Example * * {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'} * diff --git a/packages/common/src/pipes/json_pipe.ts b/packages/common/src/pipes/json_pipe.ts index c0c2d81ee9..9603b59991 100644 --- a/packages/common/src/pipes/json_pipe.ts +++ b/packages/common/src/pipes/json_pipe.ts @@ -18,9 +18,8 @@ import {Pipe, PipeTransform} from '@angular/core'; * * The following component uses a JSON pipe to convert an object * to JSON format, and displays the string in both formats for comparison. - - * {@example common/pipes/ts/json_pipe.ts region='JsonPipe'} * + * {@example common/pipes/ts/json_pipe.ts region='JsonPipe'} * */ @Pipe({name: 'json', pure: false}) diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 26a9cec33c..144949c578 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -19,20 +19,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * formatted according to locale rules that determine group sizing and * separator, decimal-point character, and other locale-specific * configurations. - * + * * If no parameters are specified, the function rounds off to the nearest value using this * [rounding method](https://en.wikibooks.org/wiki/Arithmetic/Rounding). * The behavior differs from that of the JavaScript ```Math.round()``` function. - * In the following case for example, the pipe rounds down where + * In the following case for example, the pipe rounds down where * ```Math.round()``` rounds up: - * + * * ```html * -2.5 | number:'1.0-0' * > -3 * Math.round(-2.5) * > -2 * ``` - * + * * @see `formatNumber()` * * @usageNotes @@ -44,7 +44,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * * - * */ @Pipe({name: 'number'}) export class DecimalPipe implements PipeTransform { diff --git a/packages/common/src/pipes/slice_pipe.ts b/packages/common/src/pipes/slice_pipe.ts index af2726382e..60fed51fe1 100644 --- a/packages/common/src/pipes/slice_pipe.ts +++ b/packages/common/src/pipes/slice_pipe.ts @@ -15,6 +15,8 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * Creates a new `Array` or `String` containing a subset (slice) of the elements. * + * @usageNotes + * * All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()` * and `String.prototype.slice()`. * @@ -31,14 +33,15 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * produces the following: * - *
  • b
    • - *
  • c
    • + * ```html + *
  • b
    • + *
  • c
    • + * ``` * - * ## String Examples + * ### String Examples * * {@example common/pipes/ts/slice_pipe.ts region='SlicePipe_string'} * - * */ @Pipe({name: 'slice', pure: false})