From 6d8b99118d2807193bc2ae22a10fba086c9d7255 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mladen=20Jakovljevi=C4=87?= <jakovljevic.mladen@gmail.com>
Date: Wed, 12 Jan 2022 21:36:09 +0100
Subject: [PATCH] docs(identity): add identity docs (#6750)

* docs(identity): add identity docs

* docs(identity): add selectively apply an operator example
---
 src/internal/util/identity.ts | 42 +++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/src/internal/util/identity.ts b/src/internal/util/identity.ts
index 6589842c03..0b07958e7e 100644
--- a/src/internal/util/identity.ts
+++ b/src/internal/util/identity.ts
@@ -1,3 +1,45 @@
+/**
+ * This function takes one parameter and just returns it. Simply put,
+ * this is like `<T>(x: T): T => x`.
+ *
+ * ## Examples
+ *
+ * This is useful in some cases when using things like `mergeMap`
+ *
+ * ```ts
+ * import { interval, take, map, range, mergeMap, identity } from 'rxjs';
+ *
+ * const source$ = interval(1000).pipe(take(5));
+ *
+ * const result$ = source$.pipe(
+ *   map(i => range(i)),
+ *   mergeMap(identity) // same as mergeMap(x => x)
+ * );
+ *
+ * result$.subscribe({
+ *   next: console.log
+ * });
+ * ```
+ *
+ * Or when you want to selectively apply an operator
+ *
+ * ```ts
+ * import { interval, take, identity } from 'rxjs';
+ *
+ * const shouldLimit = () => Math.random() < 0.5;
+ *
+ * const source$ = interval(1000);
+ *
+ * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);
+ *
+ * result$.subscribe({
+ *   next: console.log
+ * });
+ * ```
+ *
+ * @param x Any value that is returned by this function
+ * @returns The value passed as the first parameter to this function
+ */
 export function identity<T>(x: T): T {
   return x;
 }