Update more docs

Author: koddsson

docs/rules/array-foreach.md

@@ -4,25 +4,17 @@ Prefer `for...of` statement instead of `Array.forEach`.
 
 ## Rule Details
 
-### Why disallow `forEach`
-
 Here's a summary of why `forEach` is disallowed, and why we prefer `for...of` for almost any use-case of `forEach`:
 
 - Allowing `forEach` encourages **layering of "bad practices"**, such as using `Array.from()` (which is less performant than using `for...of`).
 - When more requirements are added on, `forEach` typically gets **chained** with other methods like `filter` or `map`, causing multiple iterations over the same Array. Encouraging `for` loops discourages chaining and encourages single-iteration logic (e.g. using a `continue` instead of `filter`).
 - `for` loops are considered "more readable" and have **clearer intent**.
 - `for...of` loops offer the **most flexibility** for iteration (especially vs `Array.from`).
 
-For more detail, here is a breakdown of each of those points:
-
-### Layering of bad practices
-
 Typically developers will reach for a `forEach` when they want to iterate over a set of items. However not all "iterables" have access to Array methods. So a developer might convert their iterable to an Array by using `Array.from(iter).forEach()`. This code has introduced performance problems, where a `for...of` loop would be more performant.
 
 `forEach` does not do anything special with the Array - it does not create a new array or does not aid in encapsulation (except for introducing a new lexical scope within the callback, which isn't a benefit considering we use `let`/`const`). We don't dissallow `map`/`filter`/`reduce` because they have a tangible effect - they create a new array - which would take _more_ code and be _less_ readable to do with a `for...of` loop, the exception being as more requirements are added, and we start chaining array methods together...
 
-### Chaining
-
 Often when using a method like `forEach` - when coming back to add new code, let's say to filter certain elements from the Array before operating on them, a developer is implicitly encouraged to use Array's method chaining to achieve this result. For example if we wanted to filter out bad apples from an Array of Apples, if the code already uses `forEach`, then its a simple addition to add `filter()`:
 
 ```diff
@@ -42,8 +34,6 @@ The problem we now have is that we're iterating multiple times over the items in
 
 Chaning isn't always necessarily bad. Chaining can advertise a series of transformations that are independant from one another, and therefore aid readability. Additionally, sometimes the "goto-style" behaviour of `continue` in for loops can hamper readability. For small Arrays, performance is not going to be of concern, but caution should be applied where there is a potentially unbounded Array (such as iterating over a fetched users list) as performance can easily become a bottleneck when unchecked.
 
-### Hiding Intent
-
 The `forEach` method passes more than just the current item it is iterating over. The signature of the `forEach` callback method is `(cur: T, i: Number, all: []T) => void` and it can _additionally_ override the `receiver` (`this` value), meaning that often the _intent_ of what the callback does is hidden. To put this another way, there is _no way_ to know what the following code operates on without reading the implementation: `forEach(polishApple)`.
 
 The `for` loop avoids this issue. Calls are explicit within the `for` loop, as they are not passed around. For example:
@@ -56,8 +46,6 @@ for (const apple of apples) {
 
 We know this code can only possibly mutate `apple`, as the return value is discarded, there is no `receiver` (`this` value) as `.call()` is not used, and it cannot operate on the whole array of `apples` because it is not passed as an argument. In this respect, we can establish what the intent of `polishApple(apple)` is far more than `forEach(polishApple)`. It is too easy for `forEach` to obscure the intent.
 
-### Flexibility
-
 While `forEach` provides a set of arguments to the callback, it is still overall _less flexible_ than a `for` loop. A `for` loop can conditionally call the callback, can pass additional arguments to the callback (which would otherwise need to be hoisted or curried), can opt to change the `receiver` (`this` value) or not pass any `receiver` at all. This extra flexibility is the reason we almost always prefer to use `for` loops over any of the Array iteration methods.
 
 A good example of how `for` loops provide flexibility, where `forEach` constrains it, is to see how an iteration would be refactored to handle async work. Consider the following...
@@ -88,9 +76,7 @@ Compare this to the `for` loop, which has a much simpler path to refactoring:
  }
 ```
 
-### See Also
-
-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
+See also https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of
 
 👎 Examples of **incorrect** code for this rule:
 

docs/rules/async-currenttarget.md

@@ -1,5 +1,7 @@
 # Async Currenttarget
 
+## Rule Details
+
 Accessing `event.currentTarget` inside an `async function()` will likely be `null` as `currentTarget` is mutated as the event is propagated.
 
 1.  A `click` event is dispatched

docs/rules/async-preventdefault.md

@@ -16,10 +16,9 @@ If you're using `async`, you likely need to wait on a promise in the event handl
 
 ```js
 document.addEventListener('click', async function (event) {
-  event.preventDefault()
-
   const data = await fetch()
-  // ...
+
+  event.preventDefault()
 })
 ```
 

docs/rules/authenticity-token.md

@@ -6,17 +6,19 @@ The Rails `form_tag` helper creates a `<form>` element with a `<input name="auth
 
 An attacker who is able to steal a user's CSRF token can perform a CSRF attack against that user. To reduce this risk, GitHub uses per-form CSRF tokens. This means that a form's method and action are embedded in that form's CSRF token. When the form is submitted, the Rails application verifies that the request's path and method match those of the CSRF token: A stolen token for the `POST /preview` endpoint will not be accepted for the `DELETE /github/github` endpoint.
 
-## CSRF tokens in JavaScript
-
 Requests initiated by JavaScript using XHR or Fetch still need to include a CSRF token. Prior to our use of per-form tokens, a common pattern for getting a valid CSRF token to include in a request was
 
+Unless the JavaScript's request is for the same method/action as the form from which it takes the CSRF token, this CSRF token will _not_ be accepted by the Rails application.
+
+The preferred way to make an HTTP request with JavaScript is to use the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API to serialize the input elements of a form:
+
+👎 Examples of **incorrect** code for this rule:
+
 ```js
 const csrfToken = this.closest('form').elements['authenticity_token'].value
 ```
 
-Unless the JavaScript's request is for the same method/action as the form from which it takes the CSRF token, this CSRF token will _not_ be accepted by the Rails application.
-
-The preferred way to make an HTTP request with JavaScript is to use the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) API to serialize the input elements of a form:
+👍 Examples of **correct** code for this rule:
 
 ```erb
 <%= form_tag "/my/endpoint" do %>

docs/rules/get-attribute.md

@@ -8,13 +8,19 @@ As HTML attributes are case insensitive, prefer using lowercase.
 
 ```js
 el.getAttribute('autoComplete')
+```
+
+```js
 el.getAttribute('dataFoo')
 ```
 
 👍 Examples of **correct** code for this rule:
 
 ```js
 el.getAttribute('autocomplete')
+```
+
+```js
 el.getAttribute('data-foo')
 ```
 

docs/rules/js-class-name.md

@@ -12,8 +12,6 @@ Since its easy for humans to cross reference usage sites and implementation, so
 
 In order to trust this system, all `js-` class names MUST be statically written as string literals. This means no dynamically constructed strings by interpolation. For the same reason, `obj.send("can_#{sym}?")` makes you feel bad deep down inside, so should `querySelector("js-" + sym)`.
 
-### Alternatives
-
 Typically dynamically constructed `js-` classes are often mixing static symbols and user data together. Like `"js-org-#{org.login}"`. In this case, separating into a `data-` attribute would be a better solution.
 
 ```html
@@ -22,24 +20,20 @@ Typically dynamically constructed `js-` classes are often mixing static symbols
 
 Allows you to select elements by `js-org-update` and still filter by the `data-org-name` attribute if you need to. Both `js-org-update` and `data-org-name` are clearly static symbols that are easy to search for.
 
-### Formatting
-
 `js-` classes must start with `js-` (obviously) and only contain lowercase letters and numbers separated by `-`s. The ESLint [`github/js-class-name`](https://github.com/github/eslint-plugin-github/blob/master/lib/rules/js-class-name.js) rule enforces this style.
 
-### See Also
-
 [@defunkt's original proposal from 2010](https://web.archive.org/web/20180902223055/http://ozmm.org/posts/slightly_obtrusive_javascript.html).
 
 👎 Examples of **incorrect** code for this rule:
 
 ```js
-
+const el = document.querySelector('.js-Foo')
 ```
 
 👍 Examples of **correct** code for this rule:
 
 ```js
-
+const el = document.querySelector('.js-foo')
 ```
 
 ## When Not To Use It

docs/rules/no-dataset.md

@@ -7,13 +7,13 @@ Due to [camel-case transformations](https://developer.mozilla.org/en-US/docs/Web
 👎 Examples of **incorrect** code for this rule:
 
 ```js
-
+el.dataset.coolThing
 ```
 
 👍 Examples of **correct** code for this rule:
 
 ```js
-
+el.getAttribute('data-cool-thing')
 ```
 
 ## When Not To Use It

docs/rules/no-implicit-buggy-globals.md

@@ -5,13 +5,15 @@
 👎 Examples of **incorrect** code for this rule:
 
 ```js
-
+var foo = 1
 ```
 
 👍 Examples of **correct** code for this rule:
 
 ```js
-
+;(function () {
+  const foo = 1
+})()
 ```
 
 ## When Not To Use It

docs/rules/no-innerText.md

@@ -5,13 +5,15 @@
 👎 Examples of **incorrect** code for this rule:
 
 ```js
-
+const el = document.createElement('div')
+el.innerText = 'foo'
 ```
 
 👍 Examples of **correct** code for this rule:
 
 ```js
-
+const el = document.createElement('div')
+el.textContent = 'foo'
 ```
 
 ## When Not To Use It