Skip to content

JSDoc: src/js/_enqueues/lib/ajax-response.js - #16098

Open
sarequl wants to merge 3 commits into
WordPress:trunkfrom
sarequl:docs/66717-ajax-response-jsdoc
Open

sarequl wants to merge 3 commits into
WordPress:trunkfrom
sarequl:docs/66717-ajax-response-jsdoc

Conversation

@sarequl

@sarequl sarequl commented Nov 19, 2026 •

Copy link
Copy Markdown

See https://core.trac.wordpress.org/ticket/66717

Summary

Adds JSDoc to src/js/_enqueues/lib/ajax-response.js: a file header, the wpAjax namespace, and documentation for the four methods (unserialize, parseAjaxResponse, invalidateForm, validateForm) with @since 2.5.0, @param and @return. Comments only, no code changes. Adds six @since 2.5.0 tags, matching when the file was added.

Also removes the trailing inline comment on parseAjaxResponse(), which the new docblock now covers.

Requested by @westonruter in the ticket; part of the umbrella ticket Core-65860.

Testing Instructions

  1. Run the JSDoc lint: npm run lint:jsdoc → exit 0.
  2. Confirm the change is comments-only: git diff --numstat origin/trunk...HEAD → 68 1 src/js/_enqueues/lib/ajax-response.js. Every added line is a comment or blank. The one removed line is the parseAjaxResponse signature, which is re-added without its trailing comment.

Adds a file header, the wpAjax namespace, and JSDoc for unserialize(),
parseAjaxResponse(), invalidateForm() and validateForm(), following the
JavaScript Documentation Standards. Comments only; no behavior change.

Props diegosa.
See #66717.
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props sarequl, westonruter, dhruvang21.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Comment thread src/js/_enqueues/lib/ajax-response.js Resolved

@westonruter westonruter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Comment by Claude Opus 5.5 (medium effort)

The docs match the code and wp-scripts lint-js passes on the file. One sentence in the wpAjax namespace docblock is inaccurate (see inline), and the PR description contradicts the diff on @since tags and links the umbrella ticket to the wrong place.

Details

Verified:

  • @since 2.5.0 is correct throughout. The file was added in r7103 with unserialize, parseAjaxResponse, and invalidateForm, and validateForm followed in r7336. Both landed before 2.5.0 shipped.
  • The parseAjaxResponse return description holds: ! re.html( … ) is always false, because .html() returns a truthy jQuery object.
  • invalidateForm does return the input elements, not the field wrappers.

PR description:

  • "no @since tags added, removed, or changed" contradicts the diff, which adds six @since 2.5.0 tags.
  • "#65860" on GitHub links to PR 65860 in this repo, not the Trac ticket. Core-65860 is the form that autolinks to Trac.

Comment thread src/js/_enqueues/lib/ajax-response.js Outdated
Comment on lines +17 to +18
* The `noPerm` and `broken` error messages are localized from PHP, with
* English fallbacks used when they are not available.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Comment by Claude Opus 5.5 (medium effort)

The English fallbacks are never actually used when the localized strings are missing: in that case wpAjax || { … } throws a ReferenceError instead. Dropping the clause would keep the docblock accurate.

Details

/* global wpAjax */ is only an ESLint hint. If wp_localize_script() did not run (it is skipped when ! did_action( 'init' )), wpAjax is an undeclared identifier, and reading it throws before the || is evaluated. The fallback object only applies if wpAjax is declared but falsy. That is a pre-existing bug and out of scope for a comments-only change, but the docs should not describe the fallback as working.

Suggested wording:

Suggested change
* The `noPerm` and `broken` error messages are localized from PHP, with
* English fallbacks used when they are not available.
* The `noPerm` and `broken` error messages are localized from PHP.

Comment thread src/js/_enqueues/lib/ajax-response.js Outdated
Comment on lines +61 to +62
* @param {string} [e] Optional. The ID of the form whose fields are marked
* as invalid when the response contains errors.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Comment by Claude Opus 5.5 (medium effort)

Nit: e can be the ID of any element that contains the fields, not necessarily a form. It is used as '#' + e + ' :input[name="…"]' and then .parents( '.form-field:first' ).

Comment thread src/js/_enqueues/lib/ajax-response.js Outdated
* @return {(Object|boolean)} The parsed response for an XML response. For other responses,
* false when an error was displayed, true otherwise.
*/
parseAjaxResponse: function( x, r, e ) { // 1 = good, 0 = strange (bad data?), -1 = you lack permission.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Comment by Claude Opus 5.5 (medium effort)

Nit: the new docblock now says more than the trailing // 1 = good, 0 = strange (bad data?), -1 = you lack permission. comment, so that comment could be removed. Keeping it is also fine for a comments-only change. A @typedef for the parsed XML response (responses[] with action, what, id, oldId, position, data, supplemental, errors, plus the top-level errors) would also help callers such as wp-lists.js, but that could be a follow-up.

Comment thread src/js/_enqueues/lib/ajax-response.js Outdated
Comment on lines +142 to +143
* Required fields (with the `form-required` class) whose visible input is
* empty are marked as invalid.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

🤖 Comment by Claude Opus 5.5 (medium effort)

Nit: form-required sits on the field wrapper (the tr or div), and only the wrapper's first visible input is checked, since .val() reads the first matched element. Wording like "Field wrappers with the form-required class whose first visible input is empty are marked as invalid." would be more precise.

Removes the note about English fallbacks for the error messages, which
never apply, and describes more precisely the element passed to
parseAjaxResponse() and the fields checked by validateForm(). Also
removes an inline comment that the docblock now covers.

See #66717.
@sarequl

sarequl commented Nov 19, 2026

Copy link
Copy Markdown
Author

Thanks @westonruter, all fixed in 9abeabb: removed the fallback sentence, reworded the e param and the form-required description, and dropped the old inline comment. I also fixed the @since line and the Core-65860 link in the description.

I left the @typedef for a follow-up, and the ReferenceError out of this PR since it's a code change.

@westonruter westonruter left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants