Skip to content

feat(lint): check descriptions of static members #29569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
caugner wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

feat(lint): check descriptions of static members #29569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a1c0871
feat(lint): check descriptions of static members
caugner Apr 29, 2026
daf8af1
chore: run `npm run lint:fix` once
caugner Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions api/CSS.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,7 +223,7 @@
},
"cqb_static": {
"__compat": {
"description": "`cbq()` static method",
"description": "`cqb()` static method",
"mdn_url": "https://developer.mozilla.org/docs/Web/API/CSS/factory_functions_static",
"spec_url": "https://drafts.css-houdini.org/css-typed-om/#dom-css-cqb",
"tags": [
Expand Down Expand Up @@ -482,7 +482,7 @@
},
"dpcm_static": {
"__compat": {
"description": "`dpqm()` static method",
"description": "`dpcm()` static method",
"mdn_url": "https://developer.mozilla.org/docs/Web/API/CSS/factory_functions_static",
"spec_url": "https://drafts.css-houdini.org/css-typed-om/#dom-css-dpcm",
"tags": [
Expand Down
2 changes: 1 addition & 1 deletion api/Document.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6275,7 +6275,7 @@
},
"parseHTML_static": {
"__compat": {
"description": "`parseHTML` static method",
"description": "`parseHTML()` static method",
"mdn_url": "https://developer.mozilla.org/docs/Web/API/Document/parseHTML_static",
"spec_url": "https://wicg.github.io/sanitizer-api/#dom-document-parsehtml",
"tags": [
Expand Down
2 changes: 1 addition & 1 deletion api/IDBKeyRange.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,7 @@
},
"only_static": {
"__compat": {
"description": "`lowerBound()` static method",
"description": "`only()` static method",
"mdn_url": "https://developer.mozilla.org/docs/Web/API/IDBKeyRange/only_static",
"spec_url": "https://w3c.github.io/IndexedDB/#ref-for-dom-idbkeyrange-only①",
"tags": [
Expand Down
2 changes: 2 additions & 0 deletions api/LanguageModel.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
},
"availability_static": {
"__compat": {
"description": "`availability()` static method",
"spec_url": "https://webmachinelearning.github.io/prompt-api/#dom-languagemodel-availability",
"support": {
"chrome": {
Expand Down Expand Up @@ -240,6 +241,7 @@
},
"create_static": {
"__compat": {
"description": "`create()` static method",
"spec_url": "https://webmachinelearning.github.io/prompt-api/#dom-languagemodel-create",
"support": {
"chrome": {
Expand Down
13 changes: 13 additions & 0 deletions lint/linter/test-descriptions.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,19 @@ const processApiData = (data, path, errors) => {
`\`${featureName.replace('_permission', '')}\` permission`,
errors,
);
} else if (featureName.endsWith('_static')) {
const memberName = featureName.slice(0, -'_static'.length);
const methodForm = `\`${memberName}()\` static method`;
const propertyForm = `\`${memberName}\` static property`;
Comment on lines +82 to +85
Copy link
Copy Markdown
Contributor Author

@caugner caugner May 4, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Elchi3 The Static API members guidelines only give an example of a static method, but there are 7 occurrences of _static being used for properties.

Should we update the guidelines to require the _static_property suffix for static properties? There is currently only 1 occurrence.

Edit: Otherwise this lint error won't be fixable.

Copy link
Copy Markdown
Member

@Elchi3 Elchi3 May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we update the guidelines to require the _static_property suffix for static properties? There is currently only 1 occurrence.

Yes, I think this rule should apply to all members (methods and properties).
(another reason why type tags would help us, I guess :)

Copy link
Copy Markdown
Contributor Author

@caugner caugner May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand. Which of these rules should apply?

  1. _static for both methods and properties
  2. _static for methods, _static_property for properties
  3. _static_method for methods, _static_property for properties

Copy link
Copy Markdown
Member

@Elchi3 Elchi3 May 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry, I got confused.

This is the way: 1. _static for both methods and properties

See also #16613 (comment)

Copy link
Copy Markdown
Contributor Author

@caugner caugner May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha, so the linter can only complain about these, not fix them automatically.

const actual = data.description || '';
if (!actual.startsWith(methodForm) && !actual.startsWith(propertyForm)) {
errors.push({
ruleName: 'static',
path,
actual,
expected: methodForm,
});
}
} else if (featureName == 'secure_context_required') {
checkDescription(
'secure context required',
Expand Down
80 changes: 80 additions & 0 deletions lint/linter/test-descriptions.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,86 @@ describe('test-descriptions', () => {
);
});

it('should check description for static method', () => {
const path = 'api.Interface.create_static';
/** @type {CompatStatement} */
const data = {
description: '',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 1);
assert.equal(
/** @type {DescriptionError} */ (errors[0]).ruleName,
'static',
);
});

it('should accept static method description', () => {
const path = 'api.Interface.create_static';
/** @type {CompatStatement} */
const data = {
description: '`create()` static method',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 0);
});

it('should accept static property description', () => {
const path = 'api.Interface.maxActions_static';
/** @type {CompatStatement} */
const data = {
description: '`maxActions` static property',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 0);
});

it('should accept static method description with trailing context', () => {
const path = 'api.console.exception_static';
/** @type {CompatStatement} */
const data = {
description: '`exception()` static method (an alias for `error()`)',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 0);
});

it('should reject static description with wrong name', () => {
const path = 'api.Interface.only_static';
/** @type {CompatStatement} */
const data = {
description: '`lowerBound()` static method',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 1);
assert.equal(
/** @type {DescriptionError} */ (errors[0]).ruleName,
'static',
);
});

it('should ignore _static_property suffix', () => {
const path = 'api.Interface.disabledFeatures_static_property';
/** @type {CompatStatement} */
const data = {
description: 'Supports `disabledFeatures` static property',
support: {},
};

const errors = processData(data, 'api', path);
assert.equal(errors.length, 0);
});

it('should check description for secure context required', () => {
const path = 'api.Interface.secure_context_required';
/** @type {CompatStatement} */
Expand Down
Loading