Fix documentation typos and mistakes (stylelint#3922)

lidicompi · Apr 4, 2019 · b4dc965 · b4dc965
1 parent d66354d
commit b4dc965
Show file tree

Hide file tree

Showing 99 changed files with 185 additions and 186 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ It's mighty because it:
 -   understands the **latest CSS syntax** including custom properties and level 4 selectors
 -   extracts **embedded styles** from HTML, markdown and CSS-in-JS object & template literals
 -   parses **CSS-like syntaxes** like SCSS, Sass, Less and SugarSS
--   has over **160 built-in rules** to catch errors, apply limits and enforce stylistic conventions
+-   has over **170 built-in rules** to catch errors, apply limits and enforce stylistic conventions
 -   supports **plugins** so you can create your own rules or make use of plugins written by the community
 -   automatically **fixes** some violations (*experimental feature*)
 -   is **well tested** with over 10000 unit tests
@@ -88,7 +88,7 @@ To help out, you can:
 -   create, enhance and debug rules using our [working on rules](docs/developer-guide/rules.md) guide
 -   improve the [documentation](docs/)
 -   add new tests to *absolutely anything*
--   improve the [performance of rules](docs/developer-guide/rules.md#improving-the-performance-of-a-new-or-an-existing-rule)
+-   improve the [performance of rules](docs/developer-guide/rules.md#improving-the-performance-of-a-rule)
 -   open [new issues](https://github.com/stylelint/stylelint/issues/new/choose) about your ideas for making stylelint better
 -   open [a pull request](https://github.com/stylelint/stylelint/compare) to show us how your idea works
 -   create or contribute to [ecosystem tools](docs/user-guide/complementary-tools.md), for example the plugin for [VS Code](https://github.com/shinnn/vscode-stylelint)

diff --git a/VISION.md b/VISION.md
@@ -56,10 +56,10 @@ The former is handled by pretty printers, like [prettier](https://github.com/pre
 
 Additionally, the built-in stylistic rules and plugins are configurable to support this diverse range of stylistic conventions. This is in contrast to pretty printers, which tend to be opinionated. The ordering of properties within declaration blocks is an example of a divisive topic, where there is no one or two dominant conventions. The [`stylelint-order`](https://www.npmjs.com/package/stylelint-order) plugin adheres to stylelint's philosophies, and can be used to lint and fix a diverse range of ordering conventions.
 
-Another example is the use of single line rules for sets of _related_ rules e.g.
+Another example is the use of single-line rules for sets of _related_ rules e.g.
 
 ```css
-/* Single line related classes */
+/* Single-line related classes */
 .class-1 { top: 0; bottom: 0; }
 .class-2 { top: 5px; right: 0; }
 .class-3 { top: 8px; left: 0; }
@@ -95,4 +95,4 @@ Provide consistency throughout, including:
 
 Provide a fast tool, and the means to test and improve performance, including:
 
--   [Benchmarking](docs/developer-guide/rules.md#improving-the-performance-of-a-new-or-an-existing-rule) of an individual rule's performance.
+-   [Benchmarking](docs/developer-guide/rules.md#improving-the-performance-of-a-rule) of an individual rule's performance.
diff --git a/docs/developer-guide/rule-testers.md b/docs/developer-guide/rule-testers.md
@@ -46,7 +46,7 @@ Required properties:
 
 Optional properties:
 
--   `syntax` {"css"|"less"|"scss"|"sugarss"}: Defaults to `"css"`. Other settings use special parsers.
+-   `syntax` {"css"|"css-in-js"|"html"|"less"|"markdown"|"sass"|"scss"|"sugarss"}: Defaults to `"css"`. Other settings use special parsers.
 -   `skipBasicChecks` {boolean}: Defaults to `false`. If `true`, a few rudimentary checks (that should almost always be included) will not be performed. You can check those out in `lib/testUtils/basicChecks.js`.
 -   `preceedingPlugins` {array}: An array of PostCSS plugins that should be run before the CSS is tested.
 -   `fix` {boolean}: Defaults to `false`. If `true`, every `reject` test-case will be tested for autofixing functionality. *Required if rule has autofixing.*

diff --git a/docs/developer-guide/rules.md b/docs/developer-guide/rules.md
@@ -79,8 +79,8 @@ Use a more specific secondary option name when accepting a *user-defined* list o
 
 Messages take one of these forms:
 
--   "Expected \[something\] \[in some context\]".
--   "Unexpected \[something\] \[in some context\]."
+-   "Expected \[something\] \[in some context\]"
+-   "Unexpected \[something\] \[in some context\]"
 
 Look at the messages of other rules to glean more conventions and patterns.
 
@@ -150,7 +150,7 @@ Please run through this checklist and ensure each point is covered by your tests
 
 ##### Commonly overlooked edge-cases
 
--   How does your rule handle variables (`$sass`, `@less`, or `var(--custom-property)`)?
+-   How does your rule handle variables (`$sass`, `@less` or `var(--custom-property)`)?
 -   How does your rule handle CSS strings (e.g. `content: "anything goes";`)?
 -   How does your rule handle CSS comments (e.g. `/* anything goes */`)?
 -   How does your rule handle `url()` functions, including data URIs (e.g. `url(anything/goes.jpg)`)?
@@ -172,7 +172,7 @@ However, this runs all 25,000+ unit tests and also linting.
 
 You can use the interactive testing prompt to run tests for just a chosen set of rules (which you'll want to do during development). For example, to run the tests for just the `color-hex-case` and `color-hex-length` rules:
 
-1.  Use `npm run watch` to start the prompt.
+1.  Run `npm run watch` to start the interactive testing prompt.
 2.  Press `p` to filter by a filename regex pattern.
 3.  Enter `color-hex-case|color-hex-length` i.e. each rule name separated by the pipe symbol (`|`).
 
@@ -181,7 +181,7 @@ You can use the interactive testing prompt to run tests for just a chosen set of
 Each rule must be accompanied by a README, fitting the following format:
 
 1.  Rule name.
-2.  Single line description.
+2.  Single-line description.
 3.  Prototypical code example.
 4.  Expanded description (if necessary).
 5.  Options.
@@ -203,7 +203,7 @@ For example:
   *       These names and values */
 ```
 
-#### Single line descriptions
+#### Single-line descriptions
 
 Take the form of:
 
@@ -215,13 +215,13 @@ Take the form of:
 #### Example patterns
 
 -   Use complete CSS patterns i.e. avoid ellipses (`...`)
--   Use standard CSS syntax (and use `css` code fences) by default.
+-   Use standard CSS syntax (and use `css` [GFM fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/)) by default.
 -   Use the minimum amount of code possible to communicate the pattern e.g. if the rule targets selectors then use an empty rule e.g. `{}`.
 -   Use `{}`, rather than `{ }` for empty rules.
 -   Use the `a` type selector by default.
 -   Use the `@media` at-rules by default.
 -   Use the `color` property by default.
--   Use *foo*, *bar* and *baz* for names e.g. `.foo`, `#bar` `--baz`
+-   Use *foo*, *bar* and *baz* for names e.g. `.foo`, `#bar`, `--baz`
 
 ### Wire up the rule
 
@@ -241,10 +241,10 @@ Once we've agreed on the direction, you can work on a pull request. Here are the
 
 1.  Run `npm run watch` to start the interactive testing prompt.
 2.  Use the `p` command to filter the active tests to just the rule you're working on.
-2.  Change the rule's validation to allow for the new option.
-3.  Add to the rule some logic (as little as possible) to make the option work.
-4.  Add new unit tests to test the option.
-5.  Add documentation about the new option.
+3.  Change the rule's validation to allow for the new option.
+4.  Add to the rule some logic (as little as possible) to make the option work.
+5.  Add new unit tests to test the option.
+6.  Add documentation about the new option.
 
 ## Fixing a bug in an existing rule
 
@@ -264,7 +264,7 @@ Deprecating rules doesn't happen very often. However, these two steps are import
 1.  Point the `stylelintReference` link to the specific version of the rule README on the GitHub website, so that it is always accessible.
 2.  Add the appropriate meta data to mark the rule as deprecated.
 
-## Improving the performance of a new or an existing rule
+## Improving the performance of a rule
 
 There's a simple way to run benchmarks on any given rule with any valid config for it:
 

diff --git a/docs/user-guide/about-rules.md b/docs/user-guide/about-rules.md
@@ -104,7 +104,7 @@ Additionally, some whitespace rule make use of another set of keywords:
 
 -   `comma`, `colon`, `semicolon`, `opening-brace`, `closing-brace`, `opening-parenthesis`, `closing-parenthesis`, `operator` or `range-operator` are used if a specific piece of punctuation in the *thing* is being targeted
 
-For example, specifying if a single space or no space must come after a comma in a function:
+For example, specifying if a single space or no space must follow a comma in a function:
 
 -   `function-comma-space-after`: `string` -   `"always"|"never"`
 
@@ -160,7 +160,7 @@ Where `*-multi-line` and `*-single-line` are in reference to the value list (the
 a,
 b {
   color: red;
-  font-family: sans, serif, monospace; /* single line value list */
+  font-family: sans, serif, monospace; /* single-line value list */
 }              ↑                    ↑
 /**            ↑                    ↑
  *  The value list start here and ends here */

diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
@@ -24,7 +24,7 @@ The configuration object can have the following properties.
 
 ### `rules`
 
-Rules determine what the linter looks for and complains about. There are [over 160](rules.md) built into stylelint. *No rules are turned on by default*, so this is where you turn on everything you want to check. All the rules must be explicitly configured as *there are no default values*.
+Rules determine what the linter looks for and complains about. There are [over 170](rules.md) built into stylelint. *No rules are turned on by default*, so this is where you turn on everything you want to check. All the rules must be explicitly configured as *there are no default values*.
 
 The `rules` property is *an object whose keys are rule names and values are rule configurations*. Each rule configuration fits one of the following formats:
 

diff --git a/docs/user-guide/css-processors.md b/docs/user-guide/css-processors.md
@@ -14,8 +14,8 @@ You can run the linter before or after your CSS processors. Depending on which p
 stylelint will automatically infer the syntax from the:
 
 -   file extension
--   value of the `lang` or `type` attribute on a `<style>` tag
--   marker on Markdown code fence
+-   `type` or `lang` attribute on `<style>` tags in HTML (and HTML-like)
+-   [info string](https://github.github.com/gfm/#info-string) on [GFM fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/) in Markdown
 
 You can force a specific syntax, though. Both the [CLI](cli.md) and the [Node.js API](node-api.md) expose a `syntax` option.
 

diff --git a/docs/user-guide/processors.md b/docs/user-guide/processors.md
@@ -8,6 +8,6 @@ Processors are community packages that enable stylelint to extract styles from w
 
 stylelint now has built-in support for many common non-stylesheet files. You may no longer need to use the following processors:
 
--   [stylelint-processor-glamorous](https://github.com/zabute/stylelint-processor-glamorous): Lint [glamorous](https://github.com/paypal/glamorous) and related css-in-js libraries using object literals.
--   [stylelint-processor-markdown](https://github.com/mapbox/stylelint-processor-markdown): Lint within Markdown's [fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
+-   [stylelint-processor-glamorous](https://github.com/zabute/stylelint-processor-glamorous): Lint [glamorous](https://github.com/paypal/glamorous) and related CSS-in-JS libraries using object literals.
+-   [stylelint-processor-markdown](https://github.com/mapbox/stylelint-processor-markdown): Lint within Markdown's [GFM fenced code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
 -   [stylelint-processor-styled-components](https://github.com/styled-components/stylelint-processor-styled-components): Lint [styled-components](https://styled-components.com) and related CSS-in-JS libraries using tagged template literals.
diff --git a/docs/user-guide/rules.md b/docs/user-guide/rules.md
@@ -50,7 +50,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 #### Declaration block
 
 -   [`declaration-block-no-duplicate-properties`](../../lib/rules/declaration-block-no-duplicate-properties/README.md): Disallow duplicate properties within declaration blocks.
--   [`declaration-block-no-shorthand-property-overrides`](../../lib/rules/declaration-block-no-shorthand-property-overrides/README.md): Disallow shorthand properties that override related longhand properties within declaration blocks.
+-   [`declaration-block-no-shorthand-property-overrides`](../../lib/rules/declaration-block-no-shorthand-property-overrides/README.md): Disallow shorthand properties that override related longhand properties.
 
 #### Block
 
@@ -78,7 +78,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 
 -   [`no-descending-specificity`](../../lib/rules/no-descending-specificity/README.md): Disallow selectors of lower specificity from coming after overriding selectors of higher specificity.
 -   [`no-duplicate-at-import-rules`](../../lib/rules/no-duplicate-at-import-rules/README.md): Disallow duplicate `@import` rules within a stylesheet.
--   [`no-duplicate-selectors`](../../lib/rules/no-duplicate-selectors/README.md): Disallow duplicate selectors.
+-   [`no-duplicate-selectors`](../../lib/rules/no-duplicate-selectors/README.md): Disallow duplicate selectors within a stylesheet.
 -   [`no-empty-source`](../../lib/rules/no-empty-source/README.md): Disallow empty sources.
 -   [`no-extra-semicolons`](../../lib/rules/no-extra-semicolons/README.md): Disallow extra semicolons (Autofixable).
 -   [`no-invalid-double-slash-comments`](../../lib/rules/no-invalid-double-slash-comments/README.md): Disallow double-slash comments (`//...`) which are not supported by CSS.
@@ -94,8 +94,8 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 
 -   [`function-blacklist`](../../lib/rules/function-blacklist/README.md): Specify a blacklist of disallowed functions.
 -   [`function-url-no-scheme-relative`](../../lib/rules/function-url-no-scheme-relative/README.md): Disallow scheme-relative urls.
--   [`function-url-scheme-blacklist`](../../lib/rules/function-url-scheme-blacklist/README.md): Specify a blacklist of disallowed url schemes.
--   [`function-url-scheme-whitelist`](../../lib/rules/function-url-scheme-whitelist/README.md): Specify a whitelist of allowed url schemes.
+-   [`function-url-scheme-blacklist`](../../lib/rules/function-url-scheme-blacklist/README.md): Specify a blacklist of disallowed URL schemes.
+-   [`function-url-scheme-whitelist`](../../lib/rules/function-url-scheme-whitelist/README.md): Specify a whitelist of allowed URL schemes.
 -   [`function-whitelist`](../../lib/rules/function-whitelist/README.md): Specify a whitelist of allowed functions.
 
 #### Keyframes
@@ -144,7 +144,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 
 #### Declaration block
 
--   [`declaration-block-single-line-max-declarations`](../../lib/rules/declaration-block-single-line-max-declarations/README.md): Limit the number of declarations within single line declaration blocks.
+-   [`declaration-block-single-line-max-declarations`](../../lib/rules/declaration-block-single-line-max-declarations/README.md): Limit the number of declarations within a single-line declaration block.
 
 #### Selector
 
@@ -212,7 +212,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 
 #### Font weight
 
--   [`font-weight-notation`](../../lib/rules/font-weight-notation/README.md): Require numeric or named (where possible) `font-weight` values.
+-   [`font-weight-notation`](../../lib/rules/font-weight-notation/README.md): Require numeric or named (where possible) `font-weight` values. Also, when named values are expected, require only valid names.
 
 #### Function
 
@@ -306,7 +306,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 -   [`selector-pseudo-class-parentheses-space-inside`](../../lib/rules/selector-pseudo-class-parentheses-space-inside/README.md): Require a single space or disallow whitespace on the inside of the parentheses within pseudo-class selectors (Autofixable).
 -   [`selector-pseudo-element-case`](../../lib/rules/selector-pseudo-element-case/README.md): Specify lowercase or uppercase for pseudo-element selectors.
 -   [`selector-pseudo-element-colon-notation`](../../lib/rules/selector-pseudo-element-colon-notation/README.md): Specify single or double colon notation for applicable pseudo-elements (Autofixable).
--   [`selector-type-case`](../../lib/rules/selector-type-case/README.md): Specify lowercase or uppercase for type selector (Autofixable).
+-   [`selector-type-case`](../../lib/rules/selector-type-case/README.md): Specify lowercase or uppercase for type selectors (Autofixable).
 
 #### Selector list
 
@@ -342,7 +342,7 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 -   [`at-rule-name-newline-after`](../../lib/rules/at-rule-name-newline-after/README.md): Require a newline after at-rule names.
 -   [`at-rule-name-space-after`](../../lib/rules/at-rule-name-space-after/README.md): Require a single space after at-rule names (Autofixable).
 -   [`at-rule-semicolon-newline-after`](../../lib/rules/at-rule-semicolon-newline-after/README.md): Require a newline after the semicolon of at-rules (Autofixable).
--   [`at-rule-semicolon-space-before`](../../lib/rules/at-rule-semicolon-space-before/README.md): Require a single space or disallow whitespace before the semicolons of at rules.
+-   [`at-rule-semicolon-space-before`](../../lib/rules/at-rule-semicolon-space-before/README.md): Require a single space or disallow whitespace before the semicolons of at-rules.
 
 #### Comment
 
@@ -357,4 +357,4 @@ Here are all the rules within stylelint, grouped first [by category](../../VISIO
 -   [`max-line-length`](../../lib/rules/max-line-length/README.md): Limit the length of a line.
 -   [`no-eol-whitespace`](../../lib/rules/no-eol-whitespace/README.md): Disallow end-of-line whitespace (Autofixable).
 -   [`no-missing-end-of-source-newline`](../../lib/rules/no-missing-end-of-source-newline/README.md): Disallow missing end-of-source newlines (Autofixable).
--   [`no-empty-first-line`](../../lib/rules/no-empty-first-line/README.md): Disallow empty first lines. (Autofixable).
+-   [`no-empty-first-line`](../../lib/rules/no-empty-first-line/README.md): Disallow empty first lines (Autofixable).
diff --git a/lib/rules/at-rule-empty-line-before/README.md b/lib/rules/at-rule-empty-line-before/README.md
@@ -104,7 +104,7 @@ a {
 
 #### `"inside-block"`
 
-Reverse the primary option for at-rules that are nested.
+Reverse the primary option for at-rules that are inside a block.
 
 For example, with `"always"`:
 
@@ -177,7 +177,7 @@ a {
 
 #### `"blockless-after-blockless"`
 
-Reverse the primary option for at-rules within a blockless group.
+Reverse the primary option for blockless at-rules that follow another blockless at-rule.
 
 Shared-line comments do not affect this option.
 
@@ -249,7 +249,7 @@ b {
 
 #### `"after-comment"`
 
-Ignore at-rules that come after a comment.
+Ignore at-rules that follow a comment.
 
 Shared-line comments do not trigger this option.
 
@@ -290,7 +290,7 @@ The following patterns are *not* considered violations:
 
 #### `"inside-block"`
 
-Ignore at-rules that are inside a declaration block.
+Ignore at-rules that are inside a block.
 
 For example, with `"always"`:
 

diff --git a/lib/rules/at-rule-name-case/README.md b/lib/rules/at-rule-name-case/README.md
@@ -5,7 +5,7 @@ Specify lowercase or uppercase for at-rules names.
 ```css
    @media (min-width: 10px) {}
 /** ↑
- * These at-rule names */
+ * This at-rule name */
 ```
 
 Only lowercase at-rule names are valid in SCSS.

diff --git a/lib/rules/at-rule-no-vendor-prefix/README.md b/lib/rules/at-rule-no-vendor-prefix/README.md
@@ -5,7 +5,7 @@ Disallow vendor prefixes for at-rules.
 ```css
     @-webkit-keyframes { 0% { top: 0; } }
 /**  ↑
- * These prefixes */
+ * This prefix */
 ```
 
 ## Options

diff --git a/lib/rules/at-rule-semicolon-space-before/README.md b/lib/rules/at-rule-semicolon-space-before/README.md
@@ -1,6 +1,6 @@
 # at-rule-semicolon-space-before
 
-Require a single space or disallow whitespace before the semicolons at-rules.
+Require a single space or disallow whitespace before the semicolons of at-rules.
 
 ```css
 @import "components/buttons";

diff --git a/lib/rules/at-rule-whitelist/README.md b/lib/rules/at-rule-whitelist/README.md
@@ -55,3 +55,4 @@ a { @extend placeholder; }
   from { top: 10px; }
   to { top: 20px; }
 }
+```
diff --git a/lib/rules/block-closing-brace-newline-after/README.md b/lib/rules/block-closing-brace-newline-after/README.md
@@ -25,7 +25,7 @@ This rule allows a trailing semicolon after the closing brace of a block. For ex
     background-color: hsl(120, 70%, 95%);
   };
 /* ↑
- * This semicolon */  
+ * This semicolon */
 }
 ```
-Original file line number
+Diff line change
@@ Expand Up / @@ -55,3 +55,4 @@ a { @extend placeholder; } @@
       from { top: 10px; }
       to { top: 20px; }
     }
+    ```