Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update jsdoc comments to better match WordPress coding standards #38466

Merged
merged 9 commits into from
Aug 20, 2024
Merged

Update jsdoc comments to better match WordPress coding standards #38466

merged 9 commits into from
Aug 20, 2024

Conversation

anomiex
Copy link
Contributor

@anomiex anomiex commented Jul 22, 2024 •
edited
Loading

Proposed changes:

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.
  • Exclude aligned tags from jsdoc/check-indentation to avoid conflict with jsdoc/check-line-alignment.

Other information:

  • Have you written new tests for your changes, if applicable?
  • Have you checked the E2E test CI results, and verified that your changes do not break them?
  • Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

Followup to #38436
Draft announcement: pdWQjU-OP-p2

Does this pull request change what data or activity we track or use?

No

Testing instructions:

  • Look sensible?

@anomiex
Update jsdoc comments to better match WordPress coding standards
a61a9de 
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.
* Remove `jsdoc/check-indentation`, which conflicts with
  `jsdoc/check-line-alignment`.
@anomiex anomiex added [Status] Needs Review To request a review from fellow Jetpack developers. Label will be renamed soon. [Type] Janitorial [Pri] Normal labels Jul 22, 2024
@anomiex anomiex requested a review from a team July 22, 2024 21:05
@anomiex anomiex self-assigned this Jul 22, 2024
@github-actions github-actions bot added [Plugin] Migration [Plugin] Protect A plugin with features to protect a site: brute force protection, security scanning, and a WAF. [Plugin] Search A plugin to add an instant search modal to your site to help visitors find content faster. [Plugin] Social Issues about the Jetpack Social plugin [Tests] Includes Tests [Tools] Development CLI The tools/cli to assist during JP development. Actions GitHub actions used to automate some of the work around releases and repository management Admin Page React-powered dashboard under the Jetpack menu E2E Tests RNA labels Jul 22, 2024
@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Jul 22, 2024 •
edited
Loading

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

  • ✅ Include a description of your PR changes.
  • ✅ Add a "[Status]" label (In Progress, Needs Team Review, ...).
  • ✅ Add testing instructions.
  • ✅ Specify whether this PR includes any changes to data or privacy.
  • ✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

The e2e test report can be found here. Please note that it can take a few minutes after the e2e tests checks are complete for the report to be available.

Follow this PR Review Process:

  1. Ensure all required checks appearing at the bottom of this PR are passing.
  2. Choose a review path based on your changes:
    • A. Team Review: add the "[Status] Needs Team Review" label
      • For most changes, including minor cross-team impacts.
      • Example: Updating a team-specific component or a small change to a shared library.
    • B. Crew Review: add the "[Status] Needs Review" label
      • For significant changes to core functionality.
      • Example: Major updates to a shared library or complex features.
    • C. Both: Start with Team, then request Crew
      • For complex changes or when you need extra confidence.
      • Example: Refactor affecting multiple systems.
  3. Get at least one approval before merging.

Still unsure? Reach out in #jetpack-developers for guidance!

Beta plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

  • WordPress.com Simple releases happen daily.
  • WoA releases happen weekly.
  • Releases to self-hosted sites happen monthly. The next release is scheduled for September 3, 2024 (scheduled code freeze on September 2, 2024).

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Debug Helper plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Search plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Social plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Protect plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Migration plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

Automattic For agencies client plugin:

  • Next scheduled release: none scheduled.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Jul 22, 2024 •
edited
Loading

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

  • To test on WoA, go to the Plugins menu on a WordPress.com Simple site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin, and enable the update/jsdoc-comments-for-wp-coding-standards branch.

    • For jetpack-mu-wpcom changes, also add define( 'JETPACK_MU_WPCOM_LOAD_VIA_BETA_PLUGIN', true ); to your wp-config.php file.

  • To test on Simple, run the following command on your sandbox:

    bin/jetpack-downloader test jetpack update/jsdoc-comments-for-wp-coding-standards

    bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/jsdoc-comments-for-wp-coding-standards

Interested in more tips and information?

  • In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
  • Read more about our development workflow here: PCYsg-eg0-p2
  • Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

@anomiex
Copy link
Contributor Author

anomiex commented Jul 22, 2024

Note we'll probably want to do a trunk merge just before merging this, to make sure this won't break on any jsdoc comments added in other commits. Then we'll want to update the pr-update-to tag to try to make sure people don't merge other PRs with jsdocs that would be broken with the changes here.

@anomiex
Copy link
Contributor Author

anomiex commented Jul 26, 2024

If someone wants to get this merged while I'm AFK, here's about how I've been resolving the conflicts in a trunk merge:

  • git checkout --theirs <files> to take the trunk versions.
  • pnpm dedupe if pnpm-lock was one of the files.
  • tools/fixup-project-versions.sh to fix any versions needing fixing.
  • pnpm lint-required --fix to re-fix any issues in non-excluded files.
  • git add everything done so far.
  • To fix just the jsdoc errors in excluded files, do this (assuming your checkout is somewhere under /usr/): for f in $(pnpm lint | perl -nwe 'BEGIN { $f = ""; } $f=$_ if /^\/usr\//; if ( /jsdoc\/(check-tag-names|check-line-alignment|check-indentation)$/ ) { print $f if $f; $f=""; }'); do echo "== $f =="; pnpm lint-file --resolve-plugins-relative-to tools/js-tools/ --fix --no-eslintrc --config <( pnpm exec eslint --print-config "$f" | jq '.rules |= pick( .["jsdoc/check-line-alignment"], .["jsdoc/check-tag-names"], .["jsdoc/check-indentation"] )' ) "$f"; done
    • Ignore the unfixable errors like "Invalid JSDoc tag name "ssr-ready"".
    • Note there are currently three fixed by that that aren't worth fixing right now since they cascade into more issues, you'd have to rewrite the entire doc blocks.
    • If you want a detailed explanation of how that works, ChatGPT's breakdown at p1722019255037219/1722019229.334469-slack-C02SV8APDTM seems accurate (but the summary at the end gets a little lost).

@zinigor
Copy link
Member

zinigor commented Aug 19, 2024

This looks like it needs another trunk merge, sorry :) I have reviewed it before my AFK, but couldn't get to merge it.

@anomiex
Copy link
Contributor Author

anomiex commented Aug 19, 2024

No problem, something like this needs very frequent merges 😀

@anomiex anomiex merged commit 199f506 into trunk Aug 20, 2024
72 of 73 checks passed
@anomiex anomiex deleted the update/jsdoc-comments-for-wp-coding-standards branch August 20, 2024 16:39
@github-actions github-actions bot removed the [Status] Needs Review To request a review from fellow Jetpack developers. Label will be renamed soon. label Aug 20, 2024
pkuliga pushed a commit that referenced this pull request Aug 23, 2024
@anomiex @pkuliga
Update jsdoc comments to better match WordPress coding standards (#38466
7b3aeeb 
)

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`.
gogdzl pushed a commit that referenced this pull request Oct 25, 2024
@anomiex @gogdzl
Update jsdoc comments to better match WordPress coding standards (#38466
2f25436 
)

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`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@zinigor zinigor zinigor approved these changes

Assignees

@anomiex anomiex

Labels
[Action] Repo Gardening Github Action: manage PR and issues in your Open Source project [Action] Required Review [Action] Test Results to Slack Actions GitHub actions used to automate some of the work around releases and repository management Admin Page React-powered dashboard under the Jetpack menu [Block] AI Assistant [Block] AI Chat [Block] Button [Block] Contact Form Form block (also see Contact Form label) [Block] Cookie Consent [Block] Donations [Block] Eventbrite [Block] GIF [Block] Google Calendar [Block] Google Docs Embed [Block] Image Compare [Block] Mailchimp [Block] Map [Block] Paid Content aka Premium Content [Block] Pay With Paypal aka Simple Payments [Block] Payments aka Unified Intro [Block] Pinterest [Block] Podcast Player [Block] Related Posts [Block] Story [Block] Subscriptions [Block] Tiled Gallery [Block] VideoPress [Block] Voice To Content E2E Tests [Extension] AI Assistant Plugin [Extension] AI Content Lens [Extension] Post Publish QR Post Panel [Feature] Contact Form [Feature] Widget Visibility [JS Package] AI Client [JS Package] Analytics [JS Package] API [JS Package] Boost Score Api [JS Package] Components [JS Package] Connection [JS Package] Eslint Changed [JS Package] Eslint Config Target Es [JS Package] I18n Check Webpack Plugin [JS Package] I18n Loader Webpack Plugin [JS Package] IDC [JS Package] Licensing [JS Package] Partner Coupon [JS Package] Publicize Components [JS Package] React Data Sync Client [JS Package] Shared Extension Utils [JS Package] Social Logos [JS Package] Storybook [JS Package] Svelte Data Sync Client [JS Package] Videopress Core [JS Package] Webpack Config [mu wpcom Feature] Block Inserter Modifications [mu wpcom Feature] Custom Css [mu wpcom Feature] Jetpack Global Styles [mu wpcom Feature] Verbum Comments Verbum, a better comment experience, app developed in the mu-wpcom plugin [mu wpcom Feature] Wpcom Block Description Links [mu wpcom Feature] Wpcom Blocks [mu wpcom Feature] Wpcom Global Styles [Package] Ad aka WordAds [Package] Assets [Package] Backup [Package] Blaze [Package] Connection [Package] Explat [Package] Forms [Package] Jetpack mu wpcom WordPress.com Features [Package] My Jetpack [Package] Search Contains core Search functionality for Jetpack and Search plugins [Package] VideoPress [Plugin] Automattic For Agencies Client [Plugin] Beta For serving live branches and the beta versions. https://github.com/automattic/jetpack-beta [Plugin] CRM Issues about the Jetpack CRM plugin [Plugin] Debug Helper Debug Tools plugin [Plugin] Jetpack Issues about the Jetpack plugin. https://wordpress.org/plugins/jetpack/ [Plugin] Migration [Plugin] Protect A plugin with features to protect a site: brute force protection, security scanning, and a WAF. [Plugin] Search A plugin to add an instant search modal to your site to help visitors find content faster. [Plugin] Social Issues about the Jetpack Social plugin [Pri] Normal RNA [Tests] Includes Tests [Tools] Development CLI The tools/cli to assist during JP development. [Type] Janitorial
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@anomiex @zinigor