[docs] no-string-throw: add missing examples. (#3701)

* [docs] no-string-throw: add missing examples.

* [docs] no-string-throw: examples for rationale.

* Code example section for no-string-throw.

src/rules/code-examples/noStringThrowRule.examples.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2013 Palantir Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as Lint from "../../index";
+
+// tslint:disable: object-literal-sort-keys
+export const codeExamples = [
+    {
+        description: "Flags throwing plain strings or concatenations of strings.",
+        config: Lint.Utils.dedent`
+            "rules": { "no-string-throw": true }
+        `,
+        pass: Lint.Utils.dedent`
+            try {
+                // ...
+            } catch (e) {
+                throw e;
+            }
+        `,
+        fail: Lint.Utils.dedent`
+            try {
+                // ...
+            } catch {
+                throw 'There was a problem.';
+            }
+        `,
+    },
+];

src/rules/noStringThrowRule.ts

@@ -19,6 +19,7 @@ import { isThrowStatement } from "tsutils";
 import * as ts from "typescript";
 
 import * as Lint from "../index";
+import { codeExamples } from "./code-examples/noStringThrowRule.examples";
 
 export class Rule extends Lint.Rules.AbstractRule {
     /* tslint:disable:object-literal-sort-keys */
@@ -27,11 +28,31 @@ export class Rule extends Lint.Rules.AbstractRule {
         description: "Flags throwing plain strings or concatenations of strings.",
         hasFix: true,
         options: null,
+        optionExamples: [true],
         optionsDescription: "Not configurable.",
         rationale: Lint.Utils.dedent`
+            Example – Doing it right
+
+            \`\`\`ts
+            // throwing an Error from typical function, whether sync or async
+            if (!productToAdd) {
+                throw new Error("How can I add new product when no value provided?");
+            }
+            \`\`\`
+
+            Example – Anti Pattern
+
+            \`\`\`ts
+            // throwing a string lacks any stack trace information and other important data properties
+            if (!productToAdd) {
+                throw ("How can I add new product when no value provided?");
+            }
+            \`\`\`
+
             Only Error objects contain a \`.stack\` member equivalent to the current stack trace.
             Primitives such as strings do not.
         `,
+        codeExamples,
         type: "functionality",
         typescriptOnly: false,
     };