Repository navigation
Conversation
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.
|
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: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. Props Bot commandsYou can trigger Props Bot actions by commenting on this PR:
|
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
westonruter
left a comment
There was a problem hiding this comment.
🤖 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.0is correct throughout. The file was added in r7103 withunserialize,parseAjaxResponse, andinvalidateForm, andvalidateFormfollowed in r7336. Both landed before 2.5.0 shipped.- The
parseAjaxResponsereturn description holds:! re.html( … )is alwaysfalse, because.html()returns a truthy jQuery object. invalidateFormdoes return theinputelements, not the field wrappers.
PR description:
- "no
@sincetags added, removed, or changed" contradicts the diff, which adds six@since 2.5.0tags. - "#65860" on GitHub links to PR 65860 in this repo, not the Trac ticket. Core-65860 is the form that autolinks to Trac.
| * The `noPerm` and `broken` error messages are localized from PHP, with | ||
| * English fallbacks used when they are not available. |
There was a problem hiding this comment.
🤖 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:
| * 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. |
| * @param {string} [e] Optional. The ID of the form whose fields are marked | ||
| * as invalid when the response contains errors. |
There was a problem hiding this comment.
🤖 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' ).
| * @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. |
There was a problem hiding this comment.
🤖 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.
| * Required fields (with the `form-required` class) whose visible input is | ||
| * empty are marked as invalid. |
There was a problem hiding this comment.
🤖 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.
|
Thanks @westonruter, all fixed in 9abeabb: removed the fallback sentence, reworded the I left the |
Co-authored-by: Weston Ruter <[email protected]>
See https://core.trac.wordpress.org/ticket/66717
Summary
Adds JSDoc to
src/js/_enqueues/lib/ajax-response.js: a file header, thewpAjaxnamespace, and documentation for the four methods (unserialize,parseAjaxResponse,invalidateForm,validateForm) with@since 2.5.0,@paramand@return. Comments only, no code changes. Adds six@since 2.5.0tags, 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
npm run lint:jsdoc→ exit 0.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 theparseAjaxResponsesignature, which is re-added without its trailing comment.