docs: improve description, examples of DecimalPipe's digitsInfo parameter (#40714)

Fixes #40671

PR Close #40714

packages/common/src/pipes/number_pipe.ts

@@ -17,33 +17,61 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * @ngModule CommonModule
  * @description
  *
- * Transforms a number into a string,
+ * Formats a value according to digit options and locale rules.
- * formatted according to locale rules that determine group sizing and
+ * Locale determines group sizing and separator,
- * separator, decimal-point character, and other locale-specific
+ * decimal point character, and other locale-specific configurations.
- * 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
- * ```Math.round()``` rounds up:
- *
- * ```html
- * -2.5 | number:'1.0-0'
- * > -3
- * Math.round(-2.5)
- * > -2
- * ```
  *
  * @see `formatNumber()`
  *
  * @usageNotes
- * The following code shows how the pipe transforms numbers
+ *
- * into text strings, according to various format specifications,
+ * ### digitsInfo
- * where the caller's default locale is `en-US`.
+ *
+ * The value's decimal representation is specified by the `digitsInfo`
+ * parameter, written in the following format:<br>
+ *
+ * ```
+ * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}
+ * ```
+ *
+ *  - `minIntegerDigits`:
+ * The minimum number of integer digits before the decimal point.
+ * Default is 1.
+ *
+ * - `minFractionDigits`:
+ * The minimum number of digits after the decimal point.
+ * Default is 0.
+ *
+ *  - `maxFractionDigits`:
+ * The maximum number of digits after the decimal point.
+ * Default is 3.
+ *
+ * If the formatted value is truncated it will be rounded using the "to-nearest" method:
+ *
+ * ```
+ * {{3.6 | number: '1.0-0'}}
+ * <!--will output '4'-->
+ *
+ * {{-3.6 | number:'1.0-0'}}
+ * <!--will output '-4'-->
+ * ```
+ *
+ * ### locale
+ *
+ * `locale` will format a value according to locale rules.
+ * Locale determines group sizing and separator,
+ * decimal point character, and other locale-specific configurations.
+ *
+ * When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default.
+ *
+ * See [Setting your app locale](guide/i18n#setting-up-the-locale-of-your-app).
  *
  * ### Example
  *
+ * The following code shows how the pipe transforms values
+ * according to various format specifications,
+ * where the caller's default locale is `en-US`.
+ *
  * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
  *
  * @publicApi
@@ -51,25 +79,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
 @Pipe({name: 'number'})
 export class DecimalPipe implements PipeTransform {
   constructor(@Inject(LOCALE_ID) private _locale: string) {}
-
-  /**
-   * @param value The number to be formatted.
-   * @param digitsInfo Decimal representation options, specified by a string
-   * in the following format:<br>
-   * <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
-   *   - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
-   * Default is `1`.
-   *   - `minFractionDigits`: The minimum number of digits after the decimal point.
-   * Default is `0`.
-   *   - `maxFractionDigits`: The maximum number of digits after the decimal point.
-   * Default is `3`.
-   * @param locale A locale code for the locale format rules to use.
-   * When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default.
-   * See [Setting your app locale](guide/i18n#setting-up-the-locale-of-your-app).
-   */
   transform(value: number|string, digitsInfo?: string, locale?: string): string|null;
   transform(value: null|undefined, digitsInfo?: string, locale?: string): null;
   transform(value: number|string|null|undefined, digitsInfo?: string, locale?: string): string|null;
+
+  /**
+   * @param value The value to be formatted.
+   * @param digitsInfo Sets digit and decimal representation.
+   * [See more](#digitsinfo).
+   * @param locale Specifies what locale format rules to use.
+   * [See more](#locale).
+   */
   transform(value: number|string|null|undefined, digitsInfo?: string, locale?: string): string
       |null {
     if (!isValue(value)) return null;

packages/examples/common/pipes/ts/e2e_test/pipe_spec.ts

@@ -75,14 +75,10 @@ describe('pipe', () => {
       browser.get(URL);
       waitForElement('number-pipe');
       const examples = element.all(by.css('number-pipe p'));
-      expect(examples.get(0).getText()).toEqual('e (no formatting): 2.718');
+      expect(examples.get(0).getText()).toEqual('No specified formatting: 3.142');
-      expect(examples.get(1).getText()).toEqual('e (3.1-5): 002.71828');
+      expect(examples.get(1).getText()).toEqual('With digitsInfo parameter specified: 0,003.14159');
-      expect(examples.get(2).getText()).toEqual('e (4.5-5): 0,002.71828');
+      expect(examples.get(2).getText())
-      expect(examples.get(3).getText()).toEqual('e (french): 0\u202f002,71828');
+          .toEqual('With digitsInfo and locale parameters specified: 0\u202f003,14159');
-      expect(examples.get(4).getText()).toEqual('pi (no formatting): 3.14');
-      expect(examples.get(5).getText()).toEqual('pi (3.1-5): 003.14');
-      expect(examples.get(6).getText()).toEqual('pi (3.5-5): 003.14000');
-      expect(examples.get(7).getText()).toEqual('-2.5 (1.0-0): -3');
     });
   });
 

packages/examples/common/pipes/ts/number_pipe.ts

@@ -11,40 +11,35 @@ import {Component} from '@angular/core';
 // we need to import data for the french locale
 import localeFr from './locale-fr';
 
-// registering french data
+registerLocaleData(localeFr, 'fr');
-registerLocaleData(localeFr);
 
 // #docregion NumberPipe
 @Component({
   selector: 'number-pipe',
   template: `<div>
-    <!--output '2.718'-->
-    <p>e (no formatting): {{e | number}}</p>
 
-    <!--output '002.71828'-->
+    <p>
-    <p>e (3.1-5): {{e | number:'3.1-5'}}</p>
+      No specified formatting:
+      {{pi | number}}
+      <!--output: '3.142'-->
+    </p>
 
-    <!--output '0,002.71828'-->
+    <p>
-    <p>e (4.5-5): {{e | number:'4.5-5'}}</p>
+      With digitsInfo parameter specified:
+      {{pi | number:'4.1-5'}}
+      <!--output: '0,003.14159'-->
+    </p>
 
-    <!--output '0 002,71828'-->
+    <p>
-    <p>e (french): {{e | number:'4.5-5':'fr'}}</p>
+      With digitsInfo and
+      locale parameters specified:
+      {{pi | number:'4.1-5':'fr'}}
+      <!--output: '0 003,14159'-->
+    </p>
 
-    <!--output '3.14'-->
-    <p>pi (no formatting): {{pi | number}}</p>
-
-    <!--output '003.14'-->
-    <p>pi (3.1-5): {{pi | number:'3.1-5'}}</p>
-
-    <!--output '003.14000'-->
-    <p>pi (3.5-5): {{pi | number:'3.5-5'}}</p>
-
-    <!--output '-3' / unlike '-2' by Math.round()-->
-    <p>-2.5 (1.0-0): {{-2.5 | number:'1.0-0'}}</p>
   </div>`
 })
 export class NumberPipeComponent {
-  pi: number = 3.14;
+  pi: number = 3.14159265359;
-  e: number = 2.718281828459045;
 }
 // #enddocregion