Documentation request: Add examples to the documentation

[m5rk]

It would be helpful to show examples of correct, incorrect code for each linter configuration scenario.

[jkillian]

Agreed that this would be a good idea @m5rk! We could add examples to the metadata that each rule has. Another easier method would be to somehow use the test code to generate the examples. However, good test cases and good code examples aren't perfectly overlapping sets, so I'm not sure if this would be possible.

[michaeljota]

How does ESLint current implementation is? They have this feature.

[juanpicado]

eslint does not do anything special in oder to generate examples, they just wrote then dow for each markdown rule definition. See https://raw.githubusercontent.com/eslint/eslint.github.io/master/docs/rules/array-bracket-newline.md .

I think this project really needs this. I've working to update rules along this week and it has been a pain to which rule match with the error displayed in the console and also sometimes is not that obvious how to fix it, specially for beginners.

This is how in eslint is being displayed

/xxx/xxx/xxx/src/myComponent.js
  13:41  error  Missing semicolon  semi

http://eslint.org/docs/rules/semi

I think the procedure for tslint should be similar approach. I know they have some kinda fancy plugins (algolia, kramdown), but, at least display some basic example should be a problem.

1. Display error in the console

This is the current approach (the second issue is hard to match with some rule if you are not familiar with all rules)

ERROR: src/myComponent.tsx[111, 6]: Unnecessary semicolon 
ERROR: src/myComponent.tsx[2, 1]: Import sources within a group must be alphabetized 

⚠️ This can be addressed via formats eg: eg: tslint -f codeFrame

It should looks like this at least

ERROR: src/myComponent.tsx[111, 6]: Unnecessary semicolon [semicolon]
ERROR: src/myComponent.tsx[2, 1]: Import sources within a group must be alphabetized [ordered-imports].

2. If you have no clue how to fix it, go to Rules website.
3. Look up the exact rule that's failing and see some basic examples.

I'm open to help.

[jkillian]

Your point about the formatters is fair - I think the default formatter should display the rule name. This would be a breaking change though, so would have to be reserved for a major version bump.

[juanpicado]

@jkillian I think the formatters is done already eg: (tslint -f codeFrame), the formatter display correctly the rule that violate the code style established in your tslint.conf. The next point was lack of examples for each rule in the main website.

[adidahiya]

One easy enhancement here would be to hyperlink to the test files hosted on Github for each rule. Our test markup syntax makes them almost as readable as code examples and these are guaranteed to be kept up to date (unlike static documentation).

[aervin]

I'm learning about Jekyll now, but perhaps someone can save me some time--can Jekyll handle optional metadata props? Not even 50% of the rules need this kind of documentation, in my opinion. Is it possible to add this documentation incrementally? To a select group of rules now, more in future?

[JoshuaKGoldberg]

☠️ TSLint's time has come! ☠️

TSLint is no longer accepting most feature requests per #4534. See typescript-eslint.io for the new, shiny way to lint your TypeScript code with ESLint. ✨

It was a pleasure open sourcing with you all!

[JoshuaKGoldberg]

🤖 Beep boop! 👉 TSLint is deprecated 👈 (#4534) and you should switch to typescript-eslint! 🤖

🔒 This issue is being locked to prevent further unnecessary discussions. Thank you! 👋