Skip to content

docs(util): improve JSDoc for parseSelector, reflow and getNextActiveElement#42479

Open
fauzan171 wants to merge 1 commit into
twbs:mainfrom
fauzan171:docs/improve-jsdoc-util-index
Open

docs(util): improve JSDoc for parseSelector, reflow and getNextActiveElement#42479
fauzan171 wants to merge 1 commit into
twbs:mainfrom
fauzan171:docs/improve-jsdoc-util-index

Conversation

@fauzan171

Copy link
Copy Markdown
Contributor

Description

This PR improves the JSDoc blocks for three public utility helpers exported from js/src/util/index.js. No runtime behaviour is changed — only comments.

parseSelector

  • Rewrote the description to be more explicit about why escaping is needed (special characters such as / and . in IDs break document.querySelector).
  • Added descriptions for @param and @returns.

reflow

  • Clarified the description ("by forcing a reflow").
  • Documented the @param and added @returns {void}.
  • Replaced the non-standard @return void with the canonical @returns {void} for consistency with the rest of the file (e.g. parseSelector).

getNextActiveElement

  • Added the missing type annotations for activeElement, shouldGetNext and isCycleAllowed (previously only list had a type).
  • Added a description for isCycleAllowed, which previously had none.
  • Fixed the return type: {Element|elem} was incorrect (elem is not a type). It is now {Element}.
  • Switched @return to @returns to match the rest of the file.

Type of changes

  • Bug fix (non-breaking change which fixes an issue)
  • Refactor
  • Docs / typos
  • New feature

Checklist

  • My code follows the code style of this project.
  • My change generates no new warnings.
  • I have read the contributing guidelines.

Why

These three helpers are the only ones in util/index.js that carry JSDoc blocks, but the blocks were inconsistent (mixed @return/@returns, missing types, missing descriptions, an invalid return type). Cleaning them up improves IDE hover hints, TypeDoc/VSCode IntelliSense and makes the intent of the helpers easier to grok at a glance.

…extActiveElement

- parseSelector: clarify description and document params/returns
- reflow: clarify description, document param/return, use @returns
- getNextActiveElement: add missing types, document isCycleAllowed,
  fix return type (was {Element|elem}), use @returns for consistency
@fauzan171 fauzan171 requested a review from a team as a code owner June 7, 2026 17:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants