From 96693ea0079d13818b9031ce892953a351f6d3b5 Mon Sep 17 00:00:00 2001 From: fisker Cheung Date: Tue, 16 Jun 2026 02:09:45 +0800 Subject: [PATCH] Improve comments (#19359) --- eslint.config.js | 3 ++- scripts/build/builders/javascript-module.js | 2 +- scripts/build/hacks/esmify-typescript-eslint.js | 2 +- scripts/build/utilities.js | 2 +- scripts/lint-changelog.js | 2 +- scripts/release/release.js | 2 +- scripts/release/steps/update-version.js | 2 +- .../jsx-identifier-case.js | 2 +- src/cli/options/parse-cli-arguments.js | 2 +- src/common/get-file-info.js | 2 +- src/config/resolve-config.js | 2 +- src/index.js | 2 +- src/language-css/parse/parse-value.js | 2 +- src/language-css/parser-postcss.js | 2 +- src/language-css/print/comma-separated-value-group.js | 4 ++-- src/language-html/constants.evaluate.js | 4 ++-- src/language-html/embed/utilities.js | 2 +- src/language-html/massage-ast/index.js | 2 +- src/language-html/parse/parse.js | 2 +- src/language-html/parse/parsers.js | 2 +- src/language-html/utilities/index.js | 6 +++--- src/language-js/comments/handle-comments.js | 2 +- src/language-js/massage-ast/index.js | 4 ++-- src/language-js/parse/babel.js | 8 ++++---- src/language-js/print/assignment.js | 2 +- src/language-js/print/index-signature.js | 2 +- src/language-js/print/key.js | 2 +- src/language-js/print/variable-declaration.js | 2 +- src/language-js/utilities/class-members.js | 2 +- .../utilities/is-meaningful-empty-statement.js | 2 +- .../utilities/is-type-annotation-a-function.js | 2 +- src/language-json/languages.evaluate.js | 2 +- src/main/comments/attach.js | 6 +++--- src/plugins/yaml.js | 2 +- tests/config/browser-prettier/main.js | 2 +- tests/config/format-test/get-fixtures.js | 2 +- tests/format/json/json-test-suite/format.test.js | 2 +- tests/format/yaml/json-test-suite/format.test.js | 2 +- tests/integration/__tests__/config-resolution.js | 2 +- tests/integration/__tests__/stdin-filepath.js | 6 +++--- tests/integration/__tests__/with-config-precedence.js | 6 +++--- website/docusaurus.config.js | 4 ++-- website/playground/urlHash.js | 2 +- 43 files changed, 59 insertions(+), 58 deletions(-) diff --git a/eslint.config.js b/eslint.config.js index ab63cd5b0..65e770bed 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -240,6 +240,8 @@ const configs = [ /* eslint-plugin-unicorn */ "unicorn/better-dom-traversing": "off", "unicorn/catch-error-name": "off", + // Doesn't work for code and JSDoc in comments + "unicorn/comment-content": "off", "unicorn/consistent-class-member-order": "off", "unicorn/consistent-compound-words": "off", "unicorn/consistent-destructuring": "off", @@ -308,7 +310,6 @@ const configs = [ "unicorn/template-indent": "error", // TODO: Enable the followings - "unicorn/comment-content": "off", "unicorn/prefer-short-arrow-method": "off", "unicorn/no-useless-concat": "off", "unicorn/no-computed-property-existence-check": "off", diff --git a/scripts/build/builders/javascript-module.js b/scripts/build/builders/javascript-module.js index 084377ccc..1430025cf 100644 --- a/scripts/build/builders/javascript-module.js +++ b/scripts/build/builders/javascript-module.js @@ -92,7 +92,7 @@ function getEsbuildOptions({ packageConfig, file, cliOptions, buildOptions }) { module: "*", process: (text, file) => transform(text, file, buildOptions), }, - // #12493, not sure what the problem is, but replace the cjs version with esm version seems fix it + // #12493, not sure what the problem is, but replace the CJS version with ESM version seems fix it { module: require.resolve("tslib"), path: require.resolve("tslib").replace(/tslib\.js$/, "tslib.es6.js"), diff --git a/scripts/build/hacks/esmify-typescript-eslint.js b/scripts/build/hacks/esmify-typescript-eslint.js index 9393752b2..cd1c27bc9 100644 --- a/scripts/build/hacks/esmify-typescript-eslint.js +++ b/scripts/build/hacks/esmify-typescript-eslint.js @@ -16,7 +16,7 @@ function esmifyTypescriptEslint(text) { ```` */ text = text.replaceAll( - // TODO: Use duplicate capture group name when eslint supports + // TODO: Use duplicate capture group name when ESLint supports /(?<=\n)(?:const|let|var) (?\w+) = (?:__importStar\(require\(["'](?.*?)["']\)\)|require\(["'](?.*?)["']\));/g, (...args) => { const groups = args.at(-1); diff --git a/scripts/build/utilities.js b/scripts/build/utilities.js index 71c1d0d5c..12a6fae86 100644 --- a/scripts/build/utilities.js +++ b/scripts/build/utilities.js @@ -15,7 +15,7 @@ Get a package file. - a package name with path like `"prettier/index.js"` @param {string} [base] -- Where the package should be solved from - a package name like `"prettier"` - - a file url like `"file://path/to/prettier"` + - a file URL like `"file://path/to/prettier"` - an absolute path like `"/path/to/prettier"` @returns {string} */ diff --git a/scripts/lint-changelog.js b/scripts/lint-changelog.js index a96348951..cbb675d68 100644 --- a/scripts/lint-changelog.js +++ b/scripts/lint-changelog.js @@ -159,7 +159,7 @@ function getCommentDescription(content, comment) { return `template comment on line ${startLine}-${endLine}`; } -// Forbid html in title +// Forbid HTML in title // https://github.com/prettier/prettier/issues/17089 function validateTitle(displayPath, title) { const processor = unified().use(remarkParse); diff --git a/scripts/release/release.js b/scripts/release/release.js index c2a2cb297..a72a5bce3 100644 --- a/scripts/release/release.js +++ b/scripts/release/release.js @@ -20,7 +20,7 @@ function runCommand(command) { }); } -// Fetch git tags to get the previous version number (i.e. the latest tag) +// Fetch Git tags to get the previous version number (i.e. the latest tag) await runCommand("git fetch --tags"); // Install script's dependencies before any require diff --git a/scripts/release/steps/update-version.js b/scripts/release/steps/update-version.js index 271c200d1..afec6b402 100644 --- a/scripts/release/steps/update-version.js +++ b/scripts/release/steps/update-version.js @@ -10,7 +10,7 @@ export default async function updateVersion({ version, next }) { return; } - // Update github issue templates + // Update GitHub issue templates processFile(".github/ISSUE_TEMPLATE/formatting.md", (content) => content.replace(/^(\*\*Prettier ).*?(\*\*)$/m, `$1${version}$2`), ); diff --git a/scripts/tools/eslint-plugin-prettier-internal-rules/jsx-identifier-case.js b/scripts/tools/eslint-plugin-prettier-internal-rules/jsx-identifier-case.js index 8e293b961..09cc25ae2 100644 --- a/scripts/tools/eslint-plugin-prettier-internal-rules/jsx-identifier-case.js +++ b/scripts/tools/eslint-plugin-prettier-internal-rules/jsx-identifier-case.js @@ -1,6 +1,6 @@ const MESSAGE_ID = "jsx-identifier-case"; -// To ignore variables, config eslint like this +// To ignore variables, config ESLint like this // {'prettier-internal-rules/jsx-identifier-case': ['error', 'name1', ... 'nameN']} export default { diff --git a/src/cli/options/parse-cli-arguments.js b/src/cli/options/parse-cli-arguments.js index 93696179c..3f954048b 100644 --- a/src/cli/options/parse-cli-arguments.js +++ b/src/cli/options/parse-cli-arguments.js @@ -22,7 +22,7 @@ function parseArgv(rawArguments, detailedOptions, logger, keys) { ...Object.fromEntries( Object.entries(normalized).map(([key, value]) => { const option = detailedOptions.find(({ name }) => name === key) || {}; - // If the flag is a prettier api option, use the option name + // If the flag is a prettier API option, use the option name // Otherwise use camel case for readability // `--ignore-unknown` -> `ignoreUnknown` return [option.forwardToApi || camelCase(key), value]; diff --git a/src/common/get-file-info.js b/src/common/get-file-info.js index 656910f21..32a051bb3 100644 --- a/src/common/get-file-info.js +++ b/src/common/get-file-info.js @@ -58,7 +58,7 @@ async function getParser(file, options) { // We should wrap this function with `withPlugins` and use `options.plugins` directly instead of loading plugins here // See #18375 #18081 - // But somehow it breaks VSCode extension, see #18353 + // But somehow it breaks VS Code extension, see #18353 plugins = ( await Promise.all([loadBuiltinPlugins(), loadPlugins(plugins)]) ).flat(); diff --git a/src/config/resolve-config.js b/src/config/resolve-config.js index da21d78e5..75af2348d 100644 --- a/src/config/resolve-config.js +++ b/src/config/resolve-config.js @@ -127,7 +127,7 @@ function mergeOverrides(configResult, filePath) { return options; } -// Based on eslint: https://github.com/eslint/eslint/blob/master/lib/config/config-ops.js +// Based on ESLint: https://github.com/eslint/eslint/blob/master/lib/config/config-ops.js function pathMatchesGlobs(filePath, patterns, excludedPatterns) { const patternList = Array.isArray(patterns) ? patterns : [patterns]; // micromatch always matches against basename when the option is enabled diff --git a/src/index.js b/src/index.js index 140642f57..d90df5946 100644 --- a/src/index.js +++ b/src/index.js @@ -91,7 +91,7 @@ const inferParser = withPlugins((file, options) => inferParserWithoutPlugins(options, { physicalFile: file }), ); -// Internal shared with cli +// Internal shared with CLI const sharedWithCli = { errors, optionCategories, diff --git a/src/language-css/parse/parse-value.js b/src/language-css/parse/parse-value.js index d33907dee..77489bef7 100644 --- a/src/language-css/parse/parse-value.js +++ b/src/language-css/parse/parse-value.js @@ -175,7 +175,7 @@ function parseNestedValue(node, options) { } function parseValue(value, options) { - // Inline javascript in Less + // Inline JavaScript in Less if (options.parser === "less" && value.startsWith("~`")) { return { type: "value-unknown", value }; } diff --git a/src/language-css/parser-postcss.js b/src/language-css/parser-postcss.js index ce4e8af8b..3e949b922 100644 --- a/src/language-css/parser-postcss.js +++ b/src/language-css/parser-postcss.js @@ -230,7 +230,7 @@ function parseNestedCSS(node, options) { } } - // only css support custom-selector + // only CSS support custom-selector if (options.parser === "css" && node.name === "custom-selector") { const customSelector = node.params.match(/:--\S+\s+/)[0].trim(); node.customSelector = customSelector; diff --git a/src/language-css/print/comma-separated-value-group.js b/src/language-css/print/comma-separated-value-group.js index 0077005b6..3fec562cd 100644 --- a/src/language-css/print/comma-separated-value-group.js +++ b/src/language-css/print/comma-separated-value-group.js @@ -280,7 +280,7 @@ function printCommaSeparatedValueGroup(path, options, print) { continue; } - // Ignore css variables and interpolation in SCSS (i.e. `--#{$var}`) + // Ignore CSS variables and interpolation in SCSS (i.e. `--#{$var}`) if (iNode.value === "--" && isHashNode(iNextNode)) { continue; } @@ -533,7 +533,7 @@ function printCommaSeparatedValueGroup(path, options, print) { return group(indent(parts)); } - // Indent is not needed for import url when url is very long + // Indent is not needed for import URL when URL is very long // and node has two groups // when type is value-comma_group // example @import url("verylongurl") projection,tv diff --git a/src/language-html/constants.evaluate.js b/src/language-html/constants.evaluate.js index 18585b11c..6db1f5fd1 100644 --- a/src/language-html/constants.evaluate.js +++ b/src/language-html/constants.evaluate.js @@ -38,7 +38,7 @@ const getCssStyleTags = (property) => const CSS_DISPLAY_TAGS = { ...getCssStyleTags("display"), - // special cases for some css display=none elements + // special cases for some CSS display=none elements template: "inline", source: "block", track: "block", @@ -48,7 +48,7 @@ const CSS_DISPLAY_TAGS = { // `noscript` is inline // noscript: "inline", - // there's no css display for these elements but they behave these ways + // there's no CSS display for these elements but they behave these ways meter: "inline-block", progress: "inline-block", object: "inline-block", diff --git a/src/language-html/embed/utilities.js b/src/language-html/embed/utilities.js index 4ff7d8518..e2a057435 100644 --- a/src/language-html/embed/utilities.js +++ b/src/language-html/embed/utilities.js @@ -46,7 +46,7 @@ async function formatAttributeValue( shouldHugJsExpression, ) { options = { - // strictly prefer single quote to avoid unnecessary html entity escape + // strictly prefer single quote to avoid unnecessary HTML entity escape __isInHtmlAttribute: true, __embeddedInHtml: true, ...options, diff --git a/src/language-html/massage-ast/index.js b/src/language-html/massage-ast/index.js index e0976edb2..05502b4e3 100644 --- a/src/language-html/massage-ast/index.js +++ b/src/language-html/massage-ast/index.js @@ -42,7 +42,7 @@ function massageAstNode(original, cloned, parent) { (parent.fullName === "img" || parent.fullName === "source")) || (name === "allow" && parent.fullName === "iframe") || name.startsWith("on") || - // Vue attributes + // Vue.js attributes name.startsWith("@") || name.startsWith(":") || name.startsWith(".") || diff --git a/src/language-html/parse/parse.js b/src/language-html/parse/parse.js index 764d30b26..276ad90f1 100644 --- a/src/language-html/parse/parse.js +++ b/src/language-html/parse/parse.js @@ -56,7 +56,7 @@ function parseVue(input, parseOptions) { (node.kind === "element" && node.name.toLowerCase() === "html"), ); - // If not Vue SFC, treat as html + // If not Vue.js SFC, treat as HTML if (isHtml) { return parseHtml(input, HTML_PARSE_OPTIONS); } diff --git a/src/language-html/parse/parsers.js b/src/language-html/parse/parsers.js index 8bca4aaed..be52dd63c 100644 --- a/src/language-html/parse/parsers.js +++ b/src/language-html/parse/parsers.js @@ -41,7 +41,7 @@ const angularParser = createParser({ tokenizeAngularLetDeclaration: true, }); -// Vue +// Vue.js const vueParser = createParser({ name: "vue", isTagNameCaseSensitive: true, diff --git a/src/language-html/utilities/index.js b/src/language-html/utilities/index.js index 259099379..a1e289106 100644 --- a/src/language-html/utilities/index.js +++ b/src/language-html/utilities/index.js @@ -53,7 +53,7 @@ function shouldPreserveContent(node, options) { return true; } - // incomplete html in ie conditional comment + // incomplete HTML in ie conditional comment // e.g. if (node.kind === "ieConditionalComment" && !node.complete) { return true; @@ -475,7 +475,7 @@ function hasParent(node, fn) { } function getNodeCssStyleDisplay(node, options) { - // Every root block in Vue SFC is a block + // Every root block in Vue.js SFC is a block if (isVueSfcBlock(node, options)) { return "block"; } @@ -535,7 +535,7 @@ function getUnescapedAttributeValue(node) { return unescapeQuoteEntities(node.value); } -// top-level elements (excluding