[docs] additional code examples for 12 rules (#3869)

* codeExample support init implementation * dedent/markdown errors need revisting * updates to new code example scheme as per ajafff * reverts prettier style updates in curly * curly docs he -> they * ICodeExample config type any -> string * Code example blocks now color-coded according to pass/fail (grn/red) * added code-examples to no-sparse-arrays, no-unnecessary-callback-wrapper and object-literal-sort-keys * Update noUnnecessaryCallbackWrapperRule.ts Accidentally committed formatting that VSCode did, has nothing to do with the commit * added code-examples to only-arrow-functions, prefer-template and typedef * more examples fixed vscode's formatting * updates to buildDocs * Improve code-example descriptions * gemfile.lock??; removes unnecessary html/scss * removes site dist * moving code examples to dedicated dir to avoid bloat in rule files * removing _site dir * move codeExamples into new directory * changed year in code-examples copyrights * Merge branch 'master' into docs/code-examples The GitHub GUI is a bit confusing * wrong import
palantir · Jul 16, 2018 · 0e8f9e0 · 0e8f9e0
1 parent 4722df4
commit 0e8f9e0
Show file tree

Hide file tree

Showing 30 changed files with 772 additions and 2 deletions.
diff --git a/src/rules/arrowReturnShorthandRule.ts b/src/rules/arrowReturnShorthandRule.ts
@@ -20,6 +20,7 @@ import * as ts from "typescript";
 
 import * as Lint from "../index";
 import { hasCommentAfterPosition } from "../language/utils";
+import { codeExamples } from "./code-examples/arrowReturnShorthand.examples";
 
 const OPTION_MULTILINE = "multiline";
 
@@ -45,6 +46,7 @@ export class Rule extends Lint.Rules.AbstractRule {
         `,
         type: "style",
         typescriptOnly: false,
+        codeExamples,
     };
     /* tslint:enable:object-literal-sort-keys */
 

diff --git a/src/rules/classNameRule.ts b/src/rules/classNameRule.ts
@@ -20,6 +20,7 @@ import * as ts from "typescript";
 
 import * as Lint from "../index";
 import { isPascalCased } from "../utils";
+import { codeExamples } from "./code-examples/className.examples";
 
 export class Rule extends Lint.Rules.AbstractRule {
     /* tslint:disable:object-literal-sort-keys */
@@ -37,6 +38,7 @@ export class Rule extends Lint.Rules.AbstractRule {
         optionExamples: [true],
         type: "style",
         typescriptOnly: false,
+        codeExamples,
     };
     /* tslint:enable:object-literal-sort-keys */
 

diff --git a/src/rules/code-examples/arrowReturnShorthand.examples.ts b/src/rules/code-examples/arrowReturnShorthand.examples.ts
@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2018 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: "Enforces usage of the shorthand return syntax when an arrow function's body does not span multiple lines.",
+        config: Lint.Utils.dedent`
+            "rules": { "arrow-return-shorthand": true }
+        `,
+        pass: Lint.Utils.dedent`
+            const calc = (x: number, y: number) => ({ add: x + y, sub: x - y, mul: x * y });
+            const calc2 = (x: number, y: number) => {
+                return { add: x + y, sub: x - y, mul: x * y }
+            };
+        `,
+        fail: Lint.Utils.dedent`
+            const calc = (x: number, y: number) => { return { add: x + y, sub: x - y, mul: x * y } };
+            const calc2 = (x: number, y: number) => {
+                return { add: x + y, sub: x - y, mul: x * y }
+            };
+       `,
+    },
+    {
+        description: "Enforces usage of the shorthand return syntax even when an arrow function's body spans multiple lines.",
+        config: Lint.Utils.dedent`
+            "rules": { "arrow-return-shorthand": [true, "multiline"] }
+        `,
+        pass: Lint.Utils.dedent`
+            const calc = (x: number, y: number) => ({ add: x + y, sub: x - y, mul: x * y });
+            const calc2 = (x: number, y: number) =>
+                ({ add: x + y, sub: x - y, mul: x * y });
+        `,
+        fail: Lint.Utils.dedent`
+            const calc = (x: number, y: number) => { return { add: x + y, sub: x - y, mul: x * y } };
+            const calc2 = (x: number, y: number) => {
+                return { add: x + y, sub: x - y, mul: x * y }
+            };
+       `,
+    },
+];
diff --git a/src/rules/code-examples/className.examples.ts b/src/rules/code-examples/className.examples.ts
@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2018 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: "Enforces PascalCased class and interface names.",
+        config: Lint.Utils.dedent`
+            "rules": { "class-name": true }
+        `,
+        pass: Lint.Utils.dedent`
+            class MyClass { }
+            interface MyInterface { }
+        `,
+        fail: Lint.Utils.dedent`
+            class myClass { }
+            interface myInterface { }
+       `,
+    },
+];
diff --git a/src/rules/code-examples/curly.examples.ts b/src/rules/code-examples/curly.examples.ts
@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2013 Palantir Technologies, Inc.
+ * Copyright 2018 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.

diff --git a/src/rules/code-examples/noAny.examples.ts b/src/rules/code-examples/noAny.examples.ts
@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2018 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: "Disallows usages of `any` as a type declaration.",
+        config: Lint.Utils.dedent`
+            "rules": { "no-any": true }
+        `,
+        pass: Lint.Utils.dedent`
+            let foo: object;
+        `,
+        fail: Lint.Utils.dedent`
+            let foo: any;
+        `,
+    },
+];
diff --git a/src/rules/code-examples/noEmptyInterface.examples.ts b/src/rules/code-examples/noEmptyInterface.examples.ts
@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2018 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: "Disallows empty interfaces.",
+        config: Lint.Utils.dedent`
+            "rules": { "no-empty-interface": true }
+        `,
+        pass: Lint.Utils.dedent`
+            interface I {
+                foo: string;
+            }
+        `,
+        fail: Lint.Utils.dedent`
+            interface I { }
+        `,
+    },
+];
diff --git a/src/rules/code-examples/noSparseArrays.examples.ts b/src/rules/code-examples/noSparseArrays.examples.ts
@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2018 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: "Disallows sparse arrays",
+        config: Lint.Utils.dedent`
+            "rules": { "no-sparse-arrays": true }
+        `,
+        pass: Lint.Utils.dedent`
+            const arr: string[] = ['elemenet1', 'element2'];
+        `,
+        fail: Lint.Utils.dedent`
+            const arr: string[] = ['elemenet1',, 'element2'];
+        `,
+    },
+];
diff --git a/src/rules/code-examples/noStringThrowRule.examples.ts b/src/rules/code-examples/noStringThrowRule.examples.ts
@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright 2013 Palantir Technologies, Inc.
+ * Copyright 2018 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.

diff --git a/src/rules/code-examples/noUnnecessaryCallbackWrapper.examples.ts b/src/rules/code-examples/noUnnecessaryCallbackWrapper.examples.ts
@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2018 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: "Disallows unnecessary callback wrappers",
+        config: Lint.Utils.dedent`
+            "rules": { "no-unnecessary-callback-wrapper": true }
+        `,
+        pass: Lint.Utils.dedent`
+            const handleContent = (content) => console.log('Handle content:', content);
+            const handleError = (error) => console.log('Handle error:', error);
+            promise.then(handleContent).catch(handleError);
+        `,
+        fail: Lint.Utils.dedent`
+            const handleContent = (content) => console.log('Handle content:', content);
+            const handleError = (error) => console.log('Handle error:', error);
+            promise.then((content) => handleContent(content)).catch((error) => handleError(error));
+        `,
+    },
+];
diff --git a/src/rules/code-examples/objectLiteralSortKeys.examples.ts b/src/rules/code-examples/objectLiteralSortKeys.examples.ts
@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2018 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: "Requires that an object literal's keys be sorted alphabetically.",
+        config: Lint.Utils.dedent`
+            "rules": { "object-literal-sort-keys": true }
+        `,
+        pass: Lint.Utils.dedent`
+            let o = {
+                bar: 2,
+                foo: 1
+            };
+        `,
+        fail: Lint.Utils.dedent`
+            let o = {
+                foo: 1,
+                bar: 2
+            };
+        `,
+    },
+    {
+        description: Lint.Utils.dedent`Requires that an object literal's keys be sorted by interface-definition.
+            If there is no interface fallback to alphabetically.`,
+        config: Lint.Utils.dedent`
+            "rules": {
+                "object-literal-sort-keys": {
+                    "options": "match-declaration-order"
+                }
+            }
+        `,
+        pass: Lint.Utils.dedent`
+            interface I {
+                foo: number;
+                bar: number;
+            }
+
+            let o: I = {
+                foo: 1,
+                bar: 2
+            };
+        `,
+        fail: Lint.Utils.dedent`
+            interface I {
+                foo: number;
+                bar: number;
+            }
+
+            let o: I = {
+                bar: 2,
+                foo: 1
+            };
+        `,
+    },
+];