docs: describe rounding behaviour of 'DecimalPipe' (#24303)

PR Close #24303

packages/common/src/pipes/number_pipe.ts

@@ -19,7 +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 
+ * ```Math.round()``` rounds up:
+ * 
+ * ```html
+ * -2.5 | number:'1.0-0'
+ * > -3
+ * Math.round(-2.5)
+ * > -2
+ * ```
+ * 
  * @see `formatNumber()`
  *
  * @usageNotes
@@ -27,6 +40,8 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * into text strings, according to various format specifications,
  * where the caller's default locale is `en-US`.
  *
+ * ### Example
+ *
  * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
  *
  *

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

@@ -38,6 +38,9 @@ registerLocaleData(localeFr);
 
     <!--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 {