docs: use @returns over @return JSDoc tag

[ntwb]

Description

Fixes per WordPress JavaScript Inline Coding Standards:

• Use @returns over @return JSDoc tag fixing ESLint jsdoc/check-tag-names "Invalid JSDoc tag" warnings
• Ensures there is a blank new line before the @returns JSDoc tag
• Ensures the @returns JSDoc tag description ends with a period.

See https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

How Has This Been Tested?

Ran npm test

Run npm run lint to confirm there are no jsdoc/check-tag-names warnings

Screenshots (jpeg or gifs if applicable):

Types of changes

JSDoc updates reducing ESLint JSDOc warnings

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows has proper inline documentation.

[gziolo]

It fixes the warnings. Those rules are quite strict, but I guess it needs to stay this way.

[aduth]

Previously, @param tag whitespace prior to the type was aligned to the @return. Since the alignment is now one off, and a blank line exists between @param and @returns anyways, I think we should drop this.

Original:

/**
 * Does a thing.
 *
 * @param  {String} foo Thing argument.
 * @return {String}     Thing returned.
 */

Revised:

/**
 * Does a thing.
 *
 * @param  {String} foo Thing argument.
 *
 * @returns {String}     Thing returned.
 */

Recommended:

/**
 * Does a thing.
 *
 * @param {String} foo Thing argument.
 *
 * @returns {String} Thing returned.
 */

[ntwb]

@aduth I thought I caught all those cases in the PR, it significantly increased the complexity of the sed regex I used for this 😏 , any that this missed I manually tweaked but must have missed a few 😞

[ntwb]

ToDo: Add new line before @returns and remove excess spacing

[ntwb]

@aduth This was the only instance that I missed I found, did you come across any others?

[ntwb]

I did some more grep'ing and found a handful of instances missed in the original PR, #4493 includes these as a follow up.

[aduth]

Thanks @ntwb , it might not have been as pervasive an issue as I first thought. I'll let you know if I come across others.

[aduth]

Most of the @param tags in this file include unnecessary whitespace before the { and after the argument name:

https://github.com/WordPress/gutenberg/blob/64b6017afcfd6543ab24f4b2326c1b7b8dc60466/editor/store/actions.js

[ntwb]

@aduth Great catch, I hadn't taken that into account :(

My next pass at the code was going to fix @params so I'll be sure to include this where applicable 👍