From bc2bf184a2cf1a9119c72f08255bad3bf4eb888c Mon Sep 17 00:00:00 2001
From: Sergej <sergej1995@gmail.com>
Date: Fri, 29 Jun 2018 08:38:39 +0200
Subject: [PATCH] docs: describe rounding behaviour of 'DecimalPipe' (#24303)

PR Close #24303
---
 packages/common/src/pipes/number_pipe.ts        | 17 ++++++++++++++++-
 .../examples/common/pipes/ts/number_pipe.ts     |  3 +++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts
index f6d8a69d11..8ad02f59b9 100644
--- a/packages/common/src/pipes/number_pipe.ts
+++ b/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>
  *
  *
diff --git a/packages/examples/common/pipes/ts/number_pipe.ts b/packages/examples/common/pipes/ts/number_pipe.ts
index b56c625864..40388a670d 100644
--- a/packages/examples/common/pipes/ts/number_pipe.ts
+++ b/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 {