Update jsdoc eslint plugin

[noahtallen]

Proposed Changes

Separating this from #72245 to simplify things. Updates eslint-plugin-jsdoc across the repo to properly support Node 18. cc @anomiex

The initial update introduced two problems:

1. Firstly, JSDoc wanted to replace Object with object.
2. Secondly, there were a lot of issues with require-returns check. It seemed to have gotten a lot smarter :)

The first fix is easy -- just add a setting which allows both Object and object. I don't see a big reason to enforce one over the other at this point, especially since we'd rather use Typescript.

The second one just meant going through several files and fixing the return type. Almost every error was caused by functions like this:

/**
 * @returns {string}
 */
function foo( x ) {
  if ( x ) {
    return "bar";
  }
}

This is obviously problematic, because the real return type is string|undefined. So I just made that adjustment in several files.

There are a few more issues reported by the main linter build below, but not enough to fail the build. I did find weird behavior in the eslint jsdoc lib, which I reported here: gajus/eslint-plugin-jsdoc#949

Testing Instructions

CI, and verify that changes make sense. The full eslint build is running here: https://teamcity.a8c.com/buildConfiguration/calypso_CheckCodeStyle/9329626

[github-actions]

Calypso Live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-54683

Jetpack Cloud live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-54683&env=jetpack

[matticbot]

This PR modifies the release build for happy-blocks

To test your changes on WordPress.com, run install-plugin.sh happy-blocks update-jsdoc-eslint-plugin on your sandbox.

To deploy your changes after merging, see the documentation: PCYsg-r7r-p2

[matticbot]

This PR modifies the release build for editing-toolkit

To test your changes on WordPress.com, run install-plugin.sh editing-toolkit update-jsdoc-eslint-plugin on your sandbox.

To deploy your changes after merging, see the documentation: PCYsg-mMA-p2

[matticbot]

This PR modifies the release build for odyssey-stats

To test your changes on WordPress.com, run install-plugin.sh odyssey-stats update-jsdoc-eslint-plugin on your sandbox.

To deploy your changes after merging, see the documentation: PejTkB-3N-p2

[matticbot]

Here is how your PR affects size of JS and CSS bundles shipped to the user's browser:

Sections (~1 bytes removed 📉 [gzipped])

name    parsed_size           gzip_size
media         +18 B  (+0.0%)       +6 B  (+0.0%)
reader        -16 B  (-0.0%)       -7 B  (-0.0%)

Sections contain code specific for a given set of routes. Is downloaded and parsed only when a particular route is navigated to.

Async-loaded Components (~1 bytes removed 📉 [gzipped])

name                                                     parsed_size           gzip_size
async-load-calypso-post-editor-media-modal                     +18 B  (+0.0%)       +6 B  (+0.0%)
async-load-calypso-post-editor-editor-media-modal              +18 B  (+0.0%)       +6 B  (+0.0%)
async-load-calypso-blocks-support-article-dialog-dialog        -16 B  (-0.0%)       -7 B  (-0.0%)
async-load-automattic-help-center                              -16 B  (-0.0%)       -7 B  (-0.0%)

React components that are loaded lazily, when a certain part of UI is displayed for the first time.

Legend

What is parsed and gzip size?

Parsed Size: Uncompressed size of the JS and CSS files. This much code needs to be parsed and stored in memory.
Gzip Size: Compressed size of the JS and CSS files. This much data needs to be downloaded over network.

Generated by performance advisor bot at iscalypsofastyet.com.

[tyxla]

Thanks for working on this 🙌

Left a few suggestions and questions, let me know what you think.

FWIW I think it looks great already!

[noahtallen]

BTW, the reason there are so many oddities in the jsdoc eslint plugin is because they actually fixed a bug with the @returns rule! Before the update, the rule would pass as long as a single return statement existed. Now, they've fixed it so that it checks every branch of the code. This is definitely better overall, because it forces us to use correct types in more places. But there do seem to be one or two bugs with this new behavior :)

Bug reports:

gajus/eslint-plugin-jsdoc#950

gajus/eslint-plugin-jsdoc#949

[tyxla]

This looks great 👍 Thanks @noahtallen! 🚀

I've committed a couple of last-minute fixes if you don't mind.

[tyxla]

Oh, I just saw #72348. Feel free to delete that commit!

[noahtallen]

Wow, they already released a fix for one of my bug reports! I updated to include that version, which let us remove the weird *|undefined definitions we had to add originally.