docs: fix more incorrect JSDoc in public APIs#8615
Conversation
Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Docs-only PR continuing the series of public API JSDoc fixes, focusing on correcting objective English grammar issues (primarily a/an agreement) across several engine modules.
Changes:
- Corrected multiple JSDoc
a/anarticle mismatches in public-facing API descriptions. - Fixed a grammatical error in
registerScriptparameter prose (pass→passed) and updated the related@examplecomment. - Updated various class/method summaries to use correct articles for vowel-sound words.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| src/core/uri.js | Fixes article usage in URI#setQuery JSDoc summary. |
| src/core/indexed-list.js | Fixes article usage in IndexedList#push JSDoc summary. |
| src/extras/render-passes/render-pass-upsample.js | Fixes article usage in RenderPassUpsample class summary. |
| src/framework/script/script-create.js | Fixes article usage and a grammar typo in registerScript JSDoc + example comment. |
| src/platform/graphics/vertex-iterator.js | Fixes article usage in VertexIteratorAccessor#get JSDoc summary and @returns. |
| src/platform/input/controller.js | Fixes article usage in Controller#registerKeys JSDoc summary. |
| src/scene/light.js | Fixes article usage in Light#updateKey JSDoc summary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
src/core/indexed-list.js:24
IndexedList#push's duplicate-key guard uses a truthiness check (if (this._index[key])), which fails when the stored index is0(the first inserted item). This allows duplicate keys to be inserted and overwrites_index[key], breaking lookups. Use an explicit existence check (e.g.!== undefinedorObject.hasOwn(this._index, key)).
* Add a new item into the list with an index key.
*
* @param {string} key - Key used to look up item in index.
* @param {object} item - Item to be stored.
*/
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Made-with: Cursor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
A fourth small docs-only pass continuing from #8612, #8613 and #8614. This batch tackles a class of issues that my hard-coded keyword search in the previous PR didn't catch: incorrect
a/anagreement before vowel-sound words. Found via arg --pcre2 '\ba\s+[aeiouAEIOU]\w*'sweep oversrc/**/*.js, with manual filtering for variable-name false positives (e.g.a is returned), genuinely consonant-sound words (a URI,a unit vector), and@examplecode.Grammar: a/an agreement
src/core/uri.js—URI.setQuery:from a Object->from an Object.src/core/indexed-list.js—IndexedList.push:with a index key->with an index key.src/extras/render-passes/render-pass-upsample.js— class summary:a up-sample filter->an up-sample filter.src/platform/input/controller.js—Controller#registerKeys:Create or update a action-> see "Factual correction" below.src/scene/light.js—Light.updateKey:Updates a integer key->Updates an integer key.src/framework/script/script-create.js—registerScriptsummary and@example:Register a existing class type->Register an existing class type.a ES6 script class->an ES6 script class(in the summary and in the@examplecomment).src/platform/graphics/vertex-iterator.js—VertexIteratorAccessor.get:a attribute component->an attribute component(summary and@returns).Other grammar
src/framework/script/script-create.js—registerScriptsummary:Register ... as a Script Type to {@link ScriptRegistry}->... as a Script Type with {@link ScriptRegistry}(per review).src/framework/script/script-create.js—registerScript@param scriptdescription:should therefore not be pass into {@link registerScript}->should therefore not be passed into {@link registerScript}.Factual correction
src/platform/input/controller.js—Controller#registerKeys: the old JSDoc said "Create or update an action…", but the method throwsAction: ${action} already registeredwhen the action is already registered — it cannot update. Reworded to "Register a new action…" and added an@throwsclause documenting the two error conditions (actionalready registered, orkeysundefined). Per review, I intentionally did not touch the matching docs on sibling methodsregisterMouse/registerPadButton, because those methods genuinely append viaappendAction()(this._actions[name] = this._actions[name] || []) and so can both create and extend an action.No runtime changes
Documentation-only. No API signatures, runtime behaviour, or generated
.d.tstypes are affected. (@throwsis not emitted by TypeScript declaration generation.)