Skip to content

Commit 51c37b1

Browse files
BBosmanBBosman
authored
docs: consistency changes (#15404)
* docs: consistency changes * chore: review comments * chore: update marked * chore: more review comments
1 parent 28e907a commit 51c37b1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+447
-411
lines changed

‎.github/ISSUE_TEMPLATE/NEW_SYNTAX.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ assignees: ''
2020

2121
**Please provide the TC39 URL for the syntax proposal:**
2222

23-
23+
<!-- for example, <https://github.com/tc39/proposal-top-level-await> -->
2424

2525
**Please provide some example code for the new syntax:**
2626

@@ -41,3 +41,5 @@ Please check off all items that have already been completed. Be sure to paste th
4141
- [ ] `eslint` update: <!-- paste PR URL for this syntax here -->
4242

4343
**Are you willing to submit a pull request to implement this syntax?**
44+
45+
<!-- markdownlint-disable-file MD004 -->

‎.github/PULL_REQUEST_TEMPLATE.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,5 +42,6 @@
4242

4343
#### What changes did you make? (Give an overview)
4444

45-
4645
#### Is there anything you'd like reviewers to focus on?
46+
47+
<!-- markdownlint-disable-file MD004 -->

‎.markdownlint.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ default: true
22

33
# Exclusions for deliberate/widespread violations
44
MD002: false # First header should be a h1 header
5+
MD004: # Unordered list style
6+
style: asterisk
57
MD007: # Unordered list indentation
68
indent: 4
79
MD013: false # Line length

‎Makefile.js

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ const checker = require("npm-license"),
1515
dateformat = require("dateformat"),
1616
fs = require("fs"),
1717
glob = require("glob"),
18+
marked = require("marked"),
1819
markdownlint = require("markdownlint"),
1920
os = require("os"),
2021
path = require("path"),
@@ -790,7 +791,9 @@ target.checkRuleFiles = function() {
790791
const basename = path.basename(filename, ".js");
791792
const docFilename = `docs/rules/${basename}.md`;
792793
const docText = cat(docFilename);
794+
const docMarkdown = marked.lexer(docText, { gfm: true, silent: false });
793795
const ruleCode = cat(filename);
796+
const knownHeaders = ["Rule Details", "Options", "Environments", "Examples", "Known Limitations", "When Not To Use It", "Related Rules", "Compatibility", "Further Reading"];
794797

795798
/**
796799
* Check if basename is present in rule-types.json file.
@@ -820,7 +823,35 @@ target.checkRuleFiles = function() {
820823
}
821824

822825
/**
823-
* Check if deprecated information is in rule code and READNE.md.
826+
* Check if all H2 headers are known and in the expected order
827+
* Only H2 headers are checked as H1 and H3 are variable and/or rule specific.
828+
* @returns {boolean} true if all headers are known and in the right order
829+
*/
830+
function hasKnownHeaders() {
831+
const headers = docMarkdown.filter(token => token.type === "heading" && token.depth === 2).map(header => header.text);
832+
833+
for (const header of headers) {
834+
if (!knownHeaders.includes(header)) {
835+
return false;
836+
}
837+
}
838+
839+
/*
840+
* Check only the subset of used headers for the correct order
841+
*/
842+
const presentHeaders = knownHeaders.filter(header => headers.includes(header));
843+
844+
for (let i = 0; i < presentHeaders.length; ++i) {
845+
if (presentHeaders[i] !== headers[i]) {
846+
return false;
847+
}
848+
}
849+
850+
return true;
851+
}
852+
853+
/**
854+
* Check if deprecated information is in rule code and README.md.
824855
* @returns {boolean} true if present
825856
* @private
826857
*/
@@ -853,6 +884,12 @@ target.checkRuleFiles = function() {
853884
console.error("Missing id in the doc page's title of rule %s", basename);
854885
errors++;
855886
}
887+
888+
// check for proper doc headers
889+
if (!hasKnownHeaders()) {
890+
console.error("Unknown or misplaced header in the doc page of rule %s, allowed headers (and their order) are: '%s'", basename, knownHeaders.join("', '"));
891+
errors++;
892+
}
856893
}
857894

858895
// check for recommended configuration

‎docs/developer-guide/working-with-custom-formatters.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -100,23 +100,23 @@ also be manually applied to that page. -->
100100

101101
Each object in the `results` array is a `result` object. Each `result` object contains the path of the file that was linted and information about linting issues that were encountered. Here are the properties available on each `result` object:
102102

103-
* **filePath**: The absolute path to the file that was linted.
104-
* **messages**: An array of `message` objects. See below for more info about messages.
105-
* **errorCount**: The number of errors for the given file.
106-
* **warningCount**: The number of warnings for the given file.
107-
* **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present.
108-
* **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available.
103+
* **filePath**: The absolute path to the file that was linted.
104+
* **messages**: An array of `message` objects. See below for more info about messages.
105+
* **errorCount**: The number of errors for the given file.
106+
* **warningCount**: The number of warnings for the given file.
107+
* **source**: The source code for the given file. This property is omitted if this file has no errors/warnings or if the `output` property is present.
108+
* **output**: The source code for the given file with as many fixes applied as possible. This property is omitted if no fix is available.
109109

110110
### The `message` Object
111111

112112
Each `message` object contains information about the ESLint rule that was triggered by some source code. The properties available on each `message` object are:
113113

114-
* **ruleId**: the ID of the rule that produced the error or warning.
115-
* **severity**: the severity of the failure, `1` for warnings and `2` for errors.
116-
* **message**: the human readable description of the error.
117-
* **line**: the line where the issue is located.
118-
* **column**: the column where the issue is located.
119-
* **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects)
114+
* **ruleId**: the ID of the rule that produced the error or warning.
115+
* **severity**: the severity of the failure, `1` for warnings and `2` for errors.
116+
* **message**: the human readable description of the error.
117+
* **line**: the line where the issue is located.
118+
* **column**: the column where the issue is located.
119+
* **nodeType**: the type of the node in the [AST](https://github.com/estree/estree/blob/master/spec.md#node-objects)
120120

121121
## The `context` Argument
122122

‎docs/rules/accessor-pairs.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,11 @@ See [no-dupe-class-members](no-dupe-class-members.md) if you also want to disall
281281

282282
You can turn this rule off if you are not concerned with the simultaneous presence of setters and getters on objects.
283283

284+
## Related Rules
285+
286+
* [no-dupe-keys](no-dupe-keys.md)
287+
* [no-dupe-class-members](no-dupe-class-members.md)
288+
284289
## Further Reading
285290

286291
* [Object Setters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set)

‎docs/rules/array-bracket-newline.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -271,10 +271,10 @@ var e = [
271271

272272
If you don't want to enforce line breaks after opening and before closing array brackets, don't enable this rule.
273273

274-
## Compatibility
275-
276-
* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)
277-
278274
## Related Rules
279275

280276
* [array-bracket-spacing](array-bracket-spacing.md)
277+
278+
## Compatibility
279+
280+
* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)

‎docs/rules/array-element-newline.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -374,10 +374,6 @@ var [i = function foo() {
374374

375375
If you don't want to enforce linebreaks between array elements, don't enable this rule.
376376

377-
## Compatibility
378-
379-
* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)
380-
381377
## Related Rules
382378

383379
* [array-bracket-spacing](array-bracket-spacing.md)
@@ -388,3 +384,7 @@ If you don't want to enforce linebreaks between array elements, don't enable thi
388384
* [max-statements-per-line](max-statements-per-line.md)
389385
* [block-spacing](block-spacing.md)
390386
* [brace-style](brace-style.md)
387+
388+
## Compatibility
389+
390+
* **JSCS:** [validateNewlineAfterArrayElements](https://jscs-dev.github.io/rule/validateNewlineAfterArrayElements)

‎docs/rules/callback-return.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -165,11 +165,11 @@ There are some cases where you might want to call a callback function more than
165165
may lead to incorrect behavior. In those cases you may want to reserve a special name for those callbacks and
166166
not include that in the list of callbacks that trigger warnings.
167167

168+
## Related Rules
169+
170+
* [handle-callback-err](handle-callback-err.md)
171+
168172
## Further Reading
169173

170174
* [The Art Of Node: Callbacks](https://github.com/maxogden/art-of-node#callbacks)
171175
* [Nodejitsu: What are the error conventions?](https://docs.nodejitsu.com/articles/errors/what-are-the-error-conventions/)
172-
173-
## Related Rules
174-
175-
* [handle-callback-err](handle-callback-err.md)

‎docs/rules/camelcase.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -241,7 +241,7 @@ Examples of **correct** code for this rule with the `{ "ignoreGlobals": true }`
241241
const foo = no_camelcased;
242242
```
243243

244-
## allow
244+
### allow
245245

246246
Examples of **correct** code for this rule with the `allow` option:
247247

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy