From baf7c98aa24cbc0a6c69ab41701acd3cf4fc36ad Mon Sep 17 00:00:00 2001
From: Matt Browne <mbrowne83@gmail.com>
Date: Fri, 28 Feb 2020 18:35:46 -0500
Subject: [PATCH] docs(eslint-plugin): [consistent-type-assertion] improve docs
 (#1651)

---
 .../docs/rules/consistent-type-assertions.md         | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/eslint-plugin/docs/rules/consistent-type-assertions.md b/packages/eslint-plugin/docs/rules/consistent-type-assertions.md
index eb0fb521374..cdf0fb7656c 100644
--- a/packages/eslint-plugin/docs/rules/consistent-type-assertions.md
+++ b/packages/eslint-plugin/docs/rules/consistent-type-assertions.md
@@ -6,6 +6,8 @@ This rule aims to standardize the use of type assertion style across the codebas
 
 Type assertions are also commonly referred as "type casting" in TypeScript (even though it is technically slightly different to what is understood by type casting in other languages), so you can think of type assertions and type casting referring to the same thing. It is essentially you saying to the TypeScript compiler, "in this case, I know better than you!".
 
+In addition to ensuring that type assertions are written in a consistent way, this rule also helps make your codebase more type-safe.
+
 ## Options
 
 ```ts
@@ -44,10 +46,16 @@ The compiler will warn for excess properties with this syntax, but not missing _
 
 The const assertion `const x = { foo: 1 } as const`, introduced in TypeScript 3.4, is considered beneficial and is ignored by this option.
 
+Assertions to `any` are also ignored by this option.
+
 Examples of **incorrect** code for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }` (and for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' }`)
 
 ```ts
 const x = { ... } as T;
+
+function foo() {
+  return { ... } as T;
+}
 ```
 
 Examples of **correct** code for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }`.
@@ -56,6 +64,10 @@ Examples of **correct** code for `{ assertionStyle: 'as', objectLiteralTypeAsser
 const x: T = { ... };
 const y = { ... } as any;
 const z = { ... } as unknown;
+
+function foo(): T {
+  return { ... };
+}
 ```
 
 Examples of **correct** code for `{ assertionStyle: 'as', objectLiteralTypeAssertions: 'allow-as-parameter' }`.