From fa1784bd7c86dfaffa5b3795fcd3c52b07a7eb69 Mon Sep 17 00:00:00 2001
From: Chris <cesperian@gmail.com>
Date: Tue, 16 Feb 2021 14:00:24 +0700
Subject: [PATCH] docs: improve examples, description of PipeTransform (#40863)

Fixes #37321

PR Close #40863
---
 .../src/change_detection/pipe_transform.ts    | 21 +++++++++----------
 .../core/ts/pipes/pipeTransFormEx_module.ts   | 15 +++++++++++++
 .../examples/core/ts/pipes/simple_truncate.ts | 16 ++++++++++++++
 packages/examples/core/ts/pipes/truncate.ts   | 16 ++++++++++++++
 4 files changed, 57 insertions(+), 11 deletions(-)
 create mode 100644 packages/examples/core/ts/pipes/pipeTransFormEx_module.ts
 create mode 100644 packages/examples/core/ts/pipes/simple_truncate.ts
 create mode 100644 packages/examples/core/ts/pipes/truncate.ts

diff --git a/packages/core/src/change_detection/pipe_transform.ts b/packages/core/src/change_detection/pipe_transform.ts
index 8e94ec25362..44e55c2669e 100644
--- a/packages/core/src/change_detection/pipe_transform.ts
+++ b/packages/core/src/change_detection/pipe_transform.ts
@@ -13,20 +13,19 @@
  *
  * @usageNotes
  *
- * In the following example, `RepeatPipe` repeats a given value a given number of times.
+ * In the following example, `TruncatePipe` returns the shortened value with an added ellipses.
  *
- * ```ts
- * import {Pipe, PipeTransform} from '@angular/core';
+ * <code-example path="core/ts/pipes/simple_truncate.ts" header="simple_truncate.ts"></code-example>
  *
- * @Pipe({name: 'repeat'})
- * export class RepeatPipe implements PipeTransform {
- *   transform(value: any, times: number) {
- *     return value.repeat(times);
- *   }
- * }
- * ```
+ * Invoking `{{ 'It was the best of times' | truncate }}` in a template will produce `It was...`.
  *
- * Invoking `{{ 'ok' | repeat:3 }}` in a template produces `okokok`.
+ * In the following example, `TruncatePipe` takes parameters that sets the truncated length and the
+ * string to append with.
+ *
+ * <code-example path="core/ts/pipes/truncate.ts" header="truncate.ts"></code-example>
+ *
+ * Invoking `{{ 'It was the best of times' | truncate:4:'....' }}` in a template will produce `It
+ * was the best....`.
  *
  * @publicApi
  */
diff --git a/packages/examples/core/ts/pipes/pipeTransFormEx_module.ts b/packages/examples/core/ts/pipes/pipeTransFormEx_module.ts
new file mode 100644
index 00000000000..e8576917a76
--- /dev/null
+++ b/packages/examples/core/ts/pipes/pipeTransFormEx_module.ts
@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {NgModule} from '@angular/core';
+import {TruncatePipe as SimpleTruncatePipe} from './simple_truncate';
+import {TruncatePipe} from './truncate';
+
+@NgModule({declarations: [SimpleTruncatePipe, TruncatePipe]})
+export class TruncateModule {
+}
diff --git a/packages/examples/core/ts/pipes/simple_truncate.ts b/packages/examples/core/ts/pipes/simple_truncate.ts
new file mode 100644
index 00000000000..cf13f996635
--- /dev/null
+++ b/packages/examples/core/ts/pipes/simple_truncate.ts
@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Pipe, PipeTransform} from '@angular/core';
+
+@Pipe({name: 'truncate'})
+export class TruncatePipe implements PipeTransform {
+  transform(value: any) {
+    return value.split(' ').slice(0, 2).join(' ') + '...';
+  }
+}
diff --git a/packages/examples/core/ts/pipes/truncate.ts b/packages/examples/core/ts/pipes/truncate.ts
new file mode 100644
index 00000000000..c37eaa96b62
--- /dev/null
+++ b/packages/examples/core/ts/pipes/truncate.ts
@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Pipe, PipeTransform} from '@angular/core';
+
+@Pipe({name: 'truncate'})
+export class TruncatePipe implements PipeTransform {
+  transform(value: any, length: number, symbol: string) {
+    return value.split(' ').slice(0, length).join(' ') + symbol;
+  }
+}