Update jsdoc comments to better match WordPress coding standards (#38466

)

More specifically, this enables a few linting rules from
`@wordpress/eslint-plugin` that had previously been disabled:

* For `jsdoc/check-tag-names`, prefer `@return` and `@yield` over
  `@returns` and `@yields`.
* Enable `jsdoc/check-line-alignment` for certain tags, most notably
  `@param.
* Update `jsdoc/check-indentation` rule config to not conflict with
  `jsdoc/check-line-alignment`.

.github/files/build-reminder-comment/check-test-reminder-comment.js

@@ -9,12 +9,12 @@ const getCheckComments = require( './get-check-comments.js' );
  * meaning that Jetpack is being built. Or `packages/jetpack-mu-wpcom`,
  * for the jetpack-mu-wpcom-plugin used on WordPress.com is being built.
  *
- * @param {GitHub} github  - Initialized Octokit REST client.
- * @param {string} owner   - Repository owner.
- * @param {string} repo    - Repository name.
- * @param {string} number  - PR number.
- * @param {Core}   core    - A reference to the @actions/core package
- * @returns {Promise} Promise resolving to an array of project strings needing testing.
+ * @param {GitHub} github - Initialized Octokit REST client.
+ * @param {string} owner  - Repository owner.
+ * @param {string} repo   - Repository name.
+ * @param {string} number - PR number.
+ * @param {Core}   core   - A reference to the @actions/core package
+ * @return {Promise} Promise resolving to an array of project strings needing testing.
  */
 async function touchedProjectsNeedingTesting( github, owner, repo, number, core ) {
 	const changed = JSON.parse( process.env.CHANGED );
@@ -46,7 +46,7 @@ async function touchedProjectsNeedingTesting( github, owner, repo, number, core
  * @param {github} github  - Pre-authenticated octokit/rest.js client with pagination plugins
  * @param {object} context - Context of the workflow run
  * @param {core}   core    - A reference to the @actions/core package
- * @returns {Promise} Promise resolving to an object with the following properties:
+ * @return {Promise} Promise resolving to an object with the following properties:
  * - {commentId} - a comment ID, or 0 if no comment is found.
  * - {projects} - an array of project strings needing testing.
  */

.github/files/build-reminder-comment/get-check-comments.js

@@ -10,7 +10,7 @@ const cache = {};
  * @param {string} number               - Issue number.
  * @param {string} testCommentIndicator - A piece of text unique to all test reminder comments.
  * @param {core}   core                 - A reference to the @actions/core package
- * @returns {Promise<Array>} Promise resolving to an array of comment IDs.
+ * @return {Promise<Array>} Promise resolving to an array of comment IDs.
  */
 async function getCheckComments( github, owner, repo, number, testCommentIndicator, core ) {
 	const testCommentIDs = [];

.pnpmfile.cjs

@@ -4,7 +4,7 @@
  * We could generally do the same with pnpm.overrides in packages.json, but this allows for comments.
  *
  * @param {object} pkg - Dependency package.json contents.
- * @returns {object} Modified pkg.
+ * @return {object} Modified pkg.
  */
 function fixDeps( pkg ) {
 	// Deps tend to get outdated due to a slow release cycle.
@@ -120,7 +120,7 @@ function fixDeps( pkg ) {
  * This can't be done with pnpm.overrides.
  *
  * @param {object} pkg - Dependency package.json contents.
- * @returns {object} Modified pkg.
+ * @return {object} Modified pkg.
  */
 function fixPeerDeps( pkg ) {
 	// Indirect deps that still depend on React <18.
@@ -165,9 +165,9 @@ function fixPeerDeps( pkg ) {
  * Pnpm package hook.
  *
  * @see https://pnpm.io/pnpmfile#hooksreadpackagepkg-context-pkg--promisepkg
- * @param {object} pkg - Dependency package.json contents.
+ * @param {object} pkg     - Dependency package.json contents.
  * @param {object} context - Pnpm object of some sort.
- * @returns {object} Modified pkg.
+ * @return {object} Modified pkg.
  */
 function readPackage( pkg, context ) {
 	if ( pkg.name ) {
@@ -182,7 +182,7 @@ function readPackage( pkg, context ) {
  *
  * @see https://pnpm.io/pnpmfile#hooksafterallresolvedlockfile-context-lockfile--promiselockfile
  * @param {object} lockfile - Lockfile data.
- * @returns {object} Modified lockfile.
+ * @return {object} Modified lockfile.
  */
 function afterAllResolved( lockfile ) {
 	// If there's only one "importer", it's probably pnpx rather than the monorepo. Don't interfere.

projects/github-actions/repo-gardening/changelog/update-jsdoc-comments-for-wp-coding-standards

@@ -0,0 +1,5 @@
+Significance: patch
+Type: changed
+Comment: Reformat jsdoc comments. No change to meaning or functionality.
+
+

projects/github-actions/repo-gardening/src/tasks/add-labels/index.js

@@ -11,7 +11,7 @@ const getFiles = require( '../../utils/get-files' );
  * - Capitalize.
  *
  * @param {string} name - Feature name.
- * @returns {string} Cleaned up feature name.
+ * @return {string} Cleaned up feature name.
  */
 function cleanName( name ) {
 	const name_exceptions = {
@@ -51,13 +51,13 @@ function cleanName( name ) {
 /**
  * Build a list of labels to add to the issue, based off our file list.
  *
- * @param {GitHub} octokit - Initialized Octokit REST client.
- * @param {string} owner   - Repository owner.
- * @param {string} repo    - Repository name.
- * @param {string} number  - PR number.
+ * @param {GitHub}  octokit  - Initialized Octokit REST client.
+ * @param {string}  owner    - Repository owner.
+ * @param {string}  repo     - Repository name.
+ * @param {string}  number   - PR number.
  * @param {boolean} isDraft  - Whether the pull request is a draft.
- * @param {boolean} isRevert  - Whether the pull request is a revert.
- * @returns {Promise<Array>} Promise resolving to an array of keywords we'll search for.
+ * @param {boolean} isRevert - Whether the pull request is a revert.
+ * @return {Promise<Array>} Promise resolving to an array of keywords we'll search for.
  */
 async function getLabelsToAdd( octokit, owner, repo, number, isDraft, isRevert ) {
 	const keywords = new Set();

projects/github-actions/repo-gardening/src/tasks/check-description/index.js

@@ -19,7 +19,7 @@ const getLabels = require( '../../utils/labels/get-labels' );
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Promise<boolean>} Promise resolving to boolean.
+ * @return {Promise<boolean>} Promise resolving to boolean.
  */
 async function hasStatusLabels( octokit, owner, repo, number ) {
 	const labels = await getLabels( octokit, owner, repo, number );
@@ -34,7 +34,7 @@ async function hasStatusLabels( octokit, owner, repo, number ) {
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Promise<boolean>} Promise resolving to boolean.
+ * @return {Promise<boolean>} Promise resolving to boolean.
  */
 async function hasNeedsReviewLabel( octokit, owner, repo, number ) {
 	const labels = await getLabels( octokit, owner, repo, number );
@@ -49,7 +49,7 @@ async function hasNeedsReviewLabel( octokit, owner, repo, number ) {
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Promise<boolean>} Promise resolving to boolean.
+ * @return {Promise<boolean>} Promise resolving to boolean.
  */
 async function hasProgressLabel( octokit, owner, repo, number ) {
 	const labels = await getLabels( octokit, owner, repo, number );
@@ -62,7 +62,7 @@ async function hasProgressLabel( octokit, owner, repo, number ) {
  *
  * @param {string} plugin        - Plugin name.
  * @param {object} nextMilestone - Information about next milestone as returnde by GitHub.
- * @returns {Promise<string>} Promise resolving to info about the release (code freeze, release date).
+ * @return {Promise<string>} Promise resolving to info about the release (code freeze, release date).
  */
 async function getMilestoneDates( plugin, nextMilestone ) {
 	let releaseDate = 'none scheduled';
@@ -119,7 +119,7 @@ If you have any questions about the release process, please ask in the #jetpack-
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Promise<string>} Promise resolving to info about the next release for that plugin.
+ * @return {Promise<string>} Promise resolving to info about the next release for that plugin.
  */
 async function buildMilestoneInfo( octokit, owner, repo, number ) {
 	const plugins = await getPluginNames( octokit, owner, repo, number );
@@ -149,7 +149,7 @@ async function buildMilestoneInfo( octokit, owner, repo, number ) {
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Promise<number>} Promise resolving to boolean.
+ * @return {Promise<number>} Promise resolving to boolean.
  */
 async function getCheckComment( octokit, owner, repo, number ) {
 	let commentID = 0;
@@ -172,10 +172,10 @@ async function getCheckComment( octokit, owner, repo, number ) {
 /**
  * Compose a list item with appropriate status check and passed message
  *
- * @param {boolean} isFailure - Boolean condition to determine if check failed.
- * @param {string} checkMessage - Sentence describing successful check.
- * @param {string} severity - Optional. Check severity. Could be one of `error`, `warning`, `notice`
- * @returns {string} - List item with status emoji and a sentence describing check.
+ * @param {boolean} isFailure    - Boolean condition to determine if check failed.
+ * @param {string}  checkMessage - Sentence describing successful check.
+ * @param {string}  severity     - Optional. Check severity. Could be one of `error`, `warning`, `notice`
+ * @return {string} - List item with status emoji and a sentence describing check.
  */
 function statusEntry( isFailure, checkMessage, severity = 'error' ) {
 	const severityMap = {
@@ -196,7 +196,7 @@ function statusEntry( isFailure, checkMessage, severity = 'error' ) {
  * @param {string} owner   - Repository owner.
  * @param {string} repo    - Repository name.
  * @param {string} number  - PR number.
- * @returns {Array} - list of affected projects without changelog entry
+ * @return {Array} - list of affected projects without changelog entry
  */
 async function getChangelogEntries( octokit, owner, repo, number ) {
 	const baseDir = getPrWorkspace();
@@ -247,7 +247,7 @@ async function getChangelogEntries( octokit, owner, repo, number ) {
  *
  * @param {WebhookPayloadPullRequest} payload - Pull request event payload.
  * @param {GitHub}                    octokit - Initialized Octokit REST client.
- * @returns {string} List of checks with appropriate status emojis.
+ * @return {string} List of checks with appropriate status emojis.
  */
 async function getStatusChecks( payload, octokit ) {
 	const { body, number, head, base } = payload.pull_request;
@@ -276,7 +276,7 @@ async function getStatusChecks( payload, octokit ) {
  * Compose a list of checks for the PR
  *
  * @param {object} statusChecks - Map of all checks with boolean as a value
- * @returns {string} part of the comment with list of checks
+ * @return {string} part of the comment with list of checks
  */
 function renderStatusChecks( statusChecks ) {
 	// No PR is too small to include a description of why you made a change
@@ -321,7 +321,7 @@ function renderStatusChecks( statusChecks ) {
  * Compose a list of recommendations based on failed checks
  *
  * @param {object} statusChecks - Map of all checks with boolean as a value
- * @returns {string} part of the comment with recommendations
+ * @return {string} part of the comment with recommendations
  */
 function renderRecommendations( statusChecks ) {
 	const recommendations = {
@@ -366,8 +366,8 @@ Guidelines: [/docs/writing-a-good-changelog-entry.md](https://github.com/Automat
  * Creates or updates a comment on PR.
  *
  * @param {WebhookPayloadPullRequest} payload - Pull request event payload.
- * @param {GitHub} octokit - Initialized Octokit REST client.
- * @param {string} comment - Comment string
+ * @param {GitHub}                    octokit - Initialized Octokit REST client.
+ * @param {string}                    comment - Comment string
  */
 async function postComment( payload, octokit, comment ) {
 	const { number } = payload.pull_request;