8000 docs: grammar nits in the root README (#1364) · invalidred/typescript-eslint@8f22ffe · GitHub 8000
[go: up one dir, main page]

Skip to content

Commit 8f22ffe

Browse files
docs: grammar nits in the root README (typescript-eslint#1364)
Co-authored-by: Brad Zacher <brad.zacher@gmail.com>
1 parent bb1671e commit 8f22ffe

File tree

1 file changed

+25
-25
lines changed

1 file changed

+25
-25
lines changed

README.md

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -34,24 +34,24 @@
3434

3535
## Getting Started
3636

37-
**[You can find our Getting Started docs here](./docs/getting-started/README.md)**
38-
**[You can find our Linting FAQ / Troubleshooting docs here](./docs/getting-started/linting/FAQ.md)**
37+
- **[You can find our Getting Started docs here](./docs/getting-started/README.md)**
38+
- **[You can find our Linting FAQ / Troubleshooting docs here](./docs/getting-started/linting/FAQ.md)**
3939

4040
The documentation below will give you an overview of what this project is, why it exists and how it works at a high level.
4141

42-
**It is very important that you are familiar with these concepts before reporting issues**, so it is a good idea to read them before raising issues.
42+
**It is crucial that you are familiar with these concepts before reporting issues**, so it is a good idea to read them before raising issues.
4343

4444
<br>
4545

4646
## What are ESLint and TypeScript, and how do they compare?
4747

4848
**ESLint** is an awesome linter for JavaScript code.
4949

50-
- Behind the scenes it uses a parser to turn your source code into a data format called an Abstract Syntax Tree (AST). This data format is then used by plugins to create assertions called lint rules around what your code should look or behave like.
50+
- Behind the scenes, it uses a parser to turn your source code into a data format called an Abstract Syntax Tree (AST). This data format is then used by plugins to create assertions called lint rules around what your code should look or behave like.
5151

5252
**TypeScript** is an awesome static code analyzer for JavaScript code, and some additional syntax that it provides on top of the underlying JavaScript language.
5353

54-
- Behind the scenes it uses a parser to turn your source code into a data format called an Abstract Syntax Tree (AST). This data format is then used by other parts of the TypeScript Compiler to do things like give you feedback on issues, allow you to refactor easily etc.
54+
- Behind the scenes, it uses a parser to turn your source code into a data format called an Abstract Syntax Tree (AST). This data format is then used by other parts of the TypeScript Compiler to do things like give you feedback on issues, allow you to refactor easily, etc.
5555

5656
They sound similar, right? They are! Both projects are ultimately striving to help you write the best JavaScript code you possibly can.
5757

@@ -63,7 +63,7 @@ As covered by the previous section, both ESLint and TypeScript rely on turning y
6363

6464
However, it turns out that ESLint and TypeScript use _different_ ASTs to each other.
6565

66-
The reason for this difference is not so interesting or important, and is simply the result of different evolutions, priorities and timelines of the projects.
66+
The reason for this difference is not so interesting or important and is simply the result of different evolutions, priorities, and timelines of the projects.
6767

6868
This project, `typescript-eslint`, exists primarily because of this major difference between the projects.
6969

@@ -105,29 +105,29 @@ For example:
105105
var x: number = 1;
106106
```
107107

108-
This is not valid JavaScript code, because it contains a so-called type annotation. When the TypeScript Compiler parses this code to produce a TypeScript AST, that `: number` syntax will be represented in the tree, and this is simply not something that ESLint can understand without additional help.
108+
This is not valid JavaScript code, because it contains a so-called type annotation. When the TypeScript Compiler parses this code to produce a TypeScript AST, the `: number` syntax will be represented in the tree, and this is simply not something that ESLint can understand without additional help.
109109

110110
However, we can leverage the fact that ESLint has been designed with these use-cases in mind!
111111

112-
It turns out that ESLint is not just one library. Instead it is composed of a few important moving parts. One of those moving parts is **the parser**. ESLint ships with a parser built in (called [`espree`](https://github.com/eslint/espree)), and so if you only ever write standard JavaScript, you don't need to care about this implementation detail.
112+
It turns out that ESLint is not just one library. Instead, it is composed of a few important moving parts. One of those moving parts is **the parser**. ESLint ships with a built-in parser (called [`espree`](https://github.com/eslint/espree)), and so if you only ever write standard JavaScript, you don't need to care about this implementation detail.
113113

114114
The great thing is, though, if we want to support non-standard JavaScript syntax, all we need to do is provide ESLint with an alternative parser to use - that is a first-class use-case offered by ESLint.
115115

116-
Knowing we can do this is just the start of course, we then need to set about creating a parser which is capable of parsing TypeScript source code, and delivering an AST which is compatible with the one ESLint expects (with some additions for things such as `: number` as mentioned above).
116+
Knowing we can do this is just the start, of course, we then need to set about creating a parser which is capable of parsing TypeScript source code, and delivering an AST which is compatible with the one ESLint expects (with some additions for things such as `: number`, as mentioned above).
117117

118-
The [`@typescript-eslint/parser`](./packages/parser/) package in this monorepo is in fact the custom ESLint parser implementation we provide to ESLint in this scenario.
118+
The [`@typescript-eslint/parser`](./packages/parser/) package in this monorepo is, in fact, the custom ESLint parser implementation we provide to ESLint in this scenario.
119119

120120
The flow and transformations that happen look a little something like this:
121121

122122
- ESLint invokes the `parser` specified in your ESLint config ([`@typescript-eslint/parser`](./packages/parser/))
123123

124-
- [`@typescript-eslint/parser`](./packages/parser/) deals with all the ESLint specific configuration, and then invokes [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/), an agnostic package that is only concerned with taking TypeScript source code and producing an appropriate AST.
124+
- [`@typescript-eslint/parser`](./packages/parser/) deals with all the ESLint specific configuration and then invokes [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/), an agnostic package that is only concerned with taking TypeScript source code and producing an appropriate AST.
125125

126-
- [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) works by invoking the TypeScript Compiler on the given source code in order to produce a TypeScript AST, and then converting that AST into a format that ESLint expects.
126+
- [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) works by invoking the TypeScript Compiler on the given source code in order to produce a TypeScript AST and then converting that AST into a format that ESLint expects.
127127

128-
**Note**: This AST format is actually more broadly used than just for ESLint. It even has its own spec and is known as **[ESTree](https://github.com/estree/estree)**, which is why our package is called `typescript-estree`.
128+
**Note**: This AST format is more broadly used than just for ESLint. It even has its own spec and is known as **[ESTree](https://github.com/estree/estree)**, which is why our package is called `typescript-estree`.
129129

130-
> Because [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) has a very specific purpose, it is reusable for tools with similar requirements to ESLint. It is therefore also used to power the amazing opinionated code formatter [Prettier](https://prettier.io)'s own TypeScript use-case.
130+
> Because [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) has a very specific purpose, it is reusable for tools with similar requirements to ESLint. It is therefore also used to power the amazing opinionated code formatter [Prettier](https://prettier.io)'s TypeScript use-case.
131131
132132
That just about covers the parsing piece! But what about the rules? This is where our plugins come into play.
133133

@@ -139,14 +139,14 @@ The short answer is, no.
139139

140140
The great news is, **there are many, many rules which will "just work"** without you having to change anything about them or provide any custom alternatives.
141141

142-
However, it is super important to be mindful all of the things we have covered in this README so far.
142+
However, it is super important to be mindful of all of the things we have covered in this README so far.
143143

144144
- TypeScript and ESLint have similar purposes
145145

146146
- This means that there will be cases where TypeScript actually solves a problem for us that we previously relied on ESLint for. These two solutions could have similar aims, but different results, or be incompatible in other ways. The best way to deal with situations like this is often to disable the relevant ESLint rule and go with the TypeScript Compiler.
147147

148148
- TypeScript is a superset of JavaScript
149-
- Even with the AST conversion in place in the parser, there can be things in the final AST which ESLint does not natively understand. If ESLint rules have been written in such a way that they make particular assumptions about ASTs, this can sometimes result in rules crashing. This can be mitigated in a number of ways - we can work with rule authors to make their code more robust, or we can provide alternative rules via our own [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/).
149+
- Even with the AST conversion in place in the parser, there can be things in the final AST which ESLint does not natively understand. If ESLint rules have been written in such a way that they make particular assumptions about ASTs, this can sometimes result in rules crashing. This can be mitigated in several ways - we can work with rule authors to make their code more robust, or we can provide alternative rules via our own [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/).
150150

151151
<br>
152152

@@ -158,19 +158,19 @@ One of the huge benefits of using TypeScript is the fact that type information c
158158

159159
When the transformation steps outlined above take place, we keep references to the original TypeScript AST and associated parser services, and so ESLint rules authors can access them in their rules.
160160

161-
We already do this in numerous rules within [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/), for example `no-unnecessary-type-assertion` and `no-inferrable-types`.
161+
We already do this in numerous rules within [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/), for example, `no-unnecessary-type-assertion` and `no-inferrable-types`.
162162

163< A3E2 /code>163
<br>
164164

165165
## What about Babel and `babel-eslint`?
166166

167167
Babel does now support parsing (but not type-checking) TypeScript source code. This is as an alternative to using the TypeScript Compiler. It also supports many other syntaxes, via plugins, which are not supported by the TypeScript Compiler. As mentioned above, `typescript-eslint` is powered by the TypeScript Compiler, so we support whatever it does.
168168

169-
The key trade-off can be summarized as: `babel-eslint` supports additional syntax which TypeScript itself does not, but `typescript-eslint` supports creating rules based on type information, which is not available to babel because there is no type-checker.
169+
The key trade-off can be summarized as `babel-eslint` supports additional syntax which TypeScript itself does not, but `typescript-eslint` supports creating rules based on type information, which is not available to babel because there is no type-checker.
170170

171171
Because they are separate projects powered by different underlying tooling, they are currently not intended to be used together.
172172

173-
Some of the people involved in `typescript-eslint` are also involved in Babel and `babel-eslint`, and in this project we are working hard to align on the AST format for non-standard JavaScript syntax. This is an ongoing effort.
173+
Some of the people involved in `typescript-eslint` are also involved in Babel and `babel-eslint`, and in this project, we are working hard to align on the AST format for non-standard JavaScript syntax. This is an ongoing effort.
174174

175175
<br>
176176

@@ -180,7 +180,7 @@ I'm so glad you asked!
180180

181181
As you can see at the [top of this repo](#typescript-eslint), these packages are already downloaded millions of times per month, and power high profile projects across our industry.
182182

183-
Nevertheless, this is a 100% community driven project. From the second you install one of the packages from this monorepo, you are a part of that community.
183+
Nevertheless, this is a 100% community-driven project. From the second you install one of the packages from this monorepo, you are a part of that community.
184184

185185
Please be respectful and mindful of how many hours of unpaid work go into building out all of the functionality we have introduced (in brief detail) above.
186186

@@ -208,7 +208,7 @@ Please follow the links below for the packages you care about.
208208

209209
- [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/) - An ESLint-specific plugin which, when used in conjunction with `@typescript-eslint/parser`, allows for TypeScript-specific linting rules to run.
210210

211-
- [`@typescript-eslint/eslint-plugin-tslint`](./packages/eslint-plugin-tslint) - An ESLint-specific plugin which runs an instance of TSLint within your ESLint setup to allow for users to more easily migrate from TSLint to ESLint.
211+
- [`@typescript-eslint/eslint-plugin-tslint`](./packages/eslint-plugin-tslint) - An ESLint-specific plugin that runs an instance of TSLint within your ESLint setup to allow for users to more easily migrate from TSLint to ESLint.
212212

213213
<br>
214214

@@ -218,7 +218,7 @@ All of the packages are published with the same version number to make it easier
218218

219219
We publish a canary release on every successful merge to master, so **you never need to wait for a new stable version to make use of any updates**.
220220

221-
Additionally, we promote the to the `latest` tag on NPM once per week, **on Mondays at 1pm Eastern**.
221+
Additionally, we promote the to the `latest` tag on NPM once per week, **on Mondays at 1 pm Eastern**.
222222

223223
The latest version under the `latest` tag is:
224224

@@ -228,7 +228,7 @@ The latest version under the `canary` tag **(latest commit to master)** is:
228228

229229
<a href="https://www.npmjs.com/package/@typescript-eslint/parser"><img src="https://img.shields.io/npm/v/@typescript-eslint/parser/canary.svg?style=flat-square" alt="NPM Version" /></a>
230230

231-
(Note: The only exceptions to the automated publishes described above are when we are in the final phases of creating the next major version of the libraries - e.g. going from `1.x.x` to `2.x.x`. During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`.)
231+
(Note: The only exception to the automated publishes described above is when we are in the final phases of creating the next major version of the libraries - e.g. going from `1.x.x` to `2.x.x`. During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`.)
232232

233233
<br>
234234

@@ -272,7 +272,7 @@ This project exists thanks to every one of the awesome people who contribute cod
272272

273273
## Financial Contributors
274274

275-
In addition to submitting code and documentation updates, you can help us sustain our community by becoming a financial contributor [[Click here to contribute - every little helps!](https://opencollective.com/typescript-eslint/contribute)]
275+
In addition to submitting code and documentation updates, you can help us sustain our community by becoming a financial contributor [[Click here to contribute - every little bit helps!](https://opencollective.com/typescript-eslint/contribute)]
276276

277277
<br>
278278

@@ -282,7 +282,7 @@ In addition to submitting code and documentation updates, you can help us sustai
282282

283283
### Organizations
284284

285-
Support this project with your organization. Your logo will show up here with a link to your website. [[Click here to contribute - every little helps!](https://opencollective.com/typescript-eslint/contribute)]
285+
Support this project with your organization. Your logo will show up here with a link to your website. [[Click here to contribute - every little bit helps!](https://opencollective.com/typescript-eslint/contribute)]
286286

287287
<a href="https://opencollective.com/typescript-eslint/organization/0/website"><img src="https://opencollective.com/typescript-eslint/organization/0/avatar.svg"></a>
288288
<a href="https://opencollective.com/typescript-eslint/organization/1/website"><img src="https://opencollective.com/typescript-eslint/organization/1/avatar.svg"></a>

0 commit comments

Comments
 (0)
0