Make WordPress Core

Opened 3 days ago

Last modified 18 hours ago

#66717 new enhancement

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

Reported by: diegosa Owned by:
Priority: low Milestone: 7.3
Component: Administration Version: 2.5
Severity: normal Keywords: has-patch
Cc: Focuses: javascript, docs

Description

This ticket adds JSDoc inline documentation to src/js/_enqueues/lib/ajax-response.js, following the JavaScript Documentation Standards.

The file had no JSDoc blocks for the wpAjax object or any of its methods (unserialize, parseAjaxResponse, invalidateForm and validateForm). The patch:

  • Adds a file header description and @since 2.5.0.
  • Documents the wpAjax namespace.
  • Adds summaries, descriptions, @since, @param and @return tags to all four methods.

The @since 2.5.0 version was determined using the git history: wp-includes/js/wp-ajax-response.js and the wpAjax object with these four methods first shipped in WordPress 2.5.0.

The patch only changes comments; no code behavior is modified. It passes the JSDoc ESLint rules (npm run lint:jsdoc).

Related: #66033

Attachments (1)

66717.diff​ (3.7 KB ) - added by diegosa 3 days ago.
Adds JSDoc to ajax-response.js.

Download all attachments as: .zip

Change History (5)

@diegosa
3 days ago

Adds JSDoc to ajax-response.js.

#1 @westonruter
44 hours ago

  • Milestone Awaiting Review → 7.3
  • Priority high → low
  • Type defect (bug) → enhancement
  • Version → 2.5

@diegosa Thanks for the ticket and patch. Would you put that diff into a pull request to facilitate review and testing?

Also, you don't need to create tickets for these fixes. You can instead just straight open PRs and associate them with the umbrella ticket #65860.

Last edited 44 hours ago by westonruter (previous) (diff)

This ticket was mentioned in ​PR #16098 on ​WordPress/wordpress-develop by ​@sarequl.


30 hours ago
#2

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, no @since tags added, removed, or changed.

Requested by @westonruter in the ticket; part of the umbrella ticket #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 0 src/js/_enqueues/lib/ajax-response.js; every added line is a comment or blank, and no line is removed.

​@dhruvang21 commented on ​PR #16098:


26 hours ago
#3

@propsbot refresh

​@sarequl commented on ​PR #16098:


18 hours ago
#4

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.

Note: See TracTickets for help on using tickets.