Make WordPress Core

Opened 3 years ago

Closed 14 months ago

Last modified 11 months ago

#43828 closed task (blessed) (fixed)

Add JSDoc ESLint script

Reported by: netweb Owned by: netweb
Milestone: 5.5 Priority: normal
Severity: normal Version:
Component: Build/Test Tools Keywords: has-patch needs-testing
Focuses: javascript Cc:


This script seeks to add a JSDoc focused ESLint script to check the JSDocs conformity with the WordPress JavaScript Docs Coding Standards

It will also greatly aid those involved with the JavaScript Inline Docs Initiative to ensure patches are conforming to the coding standards.

To test and use this npm script run, npm install and then npm run lint:jsdoc in the terminal console.

A sister pull request add similar functionality has been in ongoing development in the Gutenberg repo:

The patch for this ticket adds the ESLint JSDoc configuration to a file named .eslintrc-jsdoc.js, this is to avoid conflicts with the work in progress of adding ESLint in #31823

Attachments (7)

43828.diff (2.2 KB) - added by netweb 3 years ago.
43828.2.diff (1.3 MB) - added by kamataryo 2 years ago.
This is refreshed patch to do linting script with @wordpress/scripts
43828.3.diff (1.7 KB) - added by kamataryo 2 years ago.
Fixed the broken patch 43828.2.dff
43828.4.diff (1.7 KB) - added by whyisjake 16 months ago.
43828.5.diff (205.6 KB) - added by whyisjake 15 months ago.
43828.6.diff (105.4 KB) - added by whyisjake 14 months ago.
43828.7.diff (106.7 KB) - added by whyisjake 14 months ago.

Download all attachments as: .zip

Change History (33)

3 years ago

#1 @atimmer
3 years ago

  • Keywords has-patch added

This would help a a lot when reviewing patches.

I am thinking, how hard would it be to add a check for the presence of @since?

#2 @netweb
3 years ago

  • Keywords needs-testing added

This patch will need a little more testing to ensure I've excluded, and not errantly omitted any files or folders that we should be checking.

Great idea for @since, I'll take a look around and see what options are available to check that it exists and ensure that it is valid syntax

#3 @jorbin
3 years ago

  • Milestone changed from 5.0 to 5.1

#4 @pento
3 years ago

  • Keywords needs-refresh added
  • Milestone changed from 5.1 to 5.2

#5 @jorbin
2 years ago

  • Milestone changed from 5.2 to 5.3

Bumping this from 5.2 due to lack of progress

This ticket was mentioned in Slack in #core-js by kamataryo. View the logs.

2 years ago

#7 @kamataryo
2 years ago

Probably we should refresh the patch with [@wordpress/scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts), which includes wp-scripts lint-js.

2 years ago

This is refreshed patch to do linting script with @wordpress/scripts

2 years ago

Fixed the broken patch 43828.2.dff

#8 @kamataryo
2 years ago

Sorry to upload 43828.2.diff which is broken and not svn diff.
43828.3.diff should be the minimum required one.

#9 @kamataryo
2 years ago

The patch 43828.3.diff includes:

  • inherit .eslintignore from the existing 43828.diff patch and match it current status
  • inherit .eslingrc.js from the existing 43828.diff patch
  • package.json update to set @wordpress/scripts as a dependency
  • Also npm scripts npm run lint:js is added to run it

#10 @netweb
2 years ago

Thanks @kamataryo, sorry I've not replied sooner, I'll take a look at the latest 43828.3.diff patch shortly

#11 @netweb
2 years ago

  • Milestone changed from 5.3 to 5.4

Punting this to 5.4 to help clear the 5.3 milestone

This ticket was mentioned in Slack in #core by peterwilsoncc. View the logs.

2 years ago

This ticket was mentioned in Slack in #core by david.baumwald. View the logs.

19 months ago

#14 @netweb
19 months ago

  • Milestone changed from 5.4 to 5.5

Punting this to 5.5 to help clear the 5.4 milestone

16 months ago

#15 @whyisjake
16 months ago

  • Keywords needs-refresh removed

Patch updated @netweb, seems to be working fine.

#16 @netweb
16 months ago

Thanks @whyisjake, might me worth trying this config, though it may have a little too much “Gutenberg” based config


Either or though, no strong opinion so feel free to commit either version 👌🏼

15 months ago

#17 @whyisjake
15 months ago

Updated, and added the "lint:jsdoc:fix": "wp-scripts lint-js --fix", to fix some things automaticaly. There are still 900+ errors, might take some manual cleanup.

#18 @netweb
14 months ago

@whyisjake A quick look at the 43828.5.diff I discovered that there are some unwanted changes in the src/wp-includes/nav-menu.php file, the very last file when viewing the patch here on trac:

  • src/wp-includes/nav-menu.php

    838838                                if ( $original_object ) {
    839839                                        $menu_item->url = get_permalink( $original_object->ID );
    840                                         /** This filter is documented in wp-includes/post-template.php */
    841                                         $original_title = apply_filters( 'the_title', $original_object->post_title, $original_object->ID );
    842840                                } else {
    843841                                        $menu_item->url      = '';
    844                                         $original_title      = '';
    845842                                        $menu_item->_invalid = true;
    846843                                }
    848                                 if ( '' === $original_title ) {
    849                                         /* translators: %d: ID of a post. */
    850                                         $original_title = sprintf( __( '#%d (no title)' ), $menu_item->object_id );
    851                                 }
     845                                $menu_item->title = $menu_item->post_title;
    853                                 $menu_item->title = ( '' === $menu_item->post_title ) ? $original_title : $menu_item->post_title;
    855847                        } elseif ( 'post_type_archive' === $menu_item->type ) {
    856848                                $object = get_post_type_object( $menu_item->object );
    857849                                if ( $object ) {

The patch is hard to review here on Trac, I think this is a good candidate to add a PR on GitHub, could you push up a PR and I'll review that there please?

#19 @whyisjake
14 months ago

@netweb, good catch. That came from another patch I was working on.

This ticket was mentioned in PR #418 on WordPress/wordpress-develop by whyisjake.

14 months ago

This is an bring in some changes to automate the testing of JSDoc blocks.

Trac ticket: https://core.trac.wordpress.org/ticket/43828

#22 in reply to: ↑ 21 @netweb
14 months ago

Replying to whyisjake:

@netweb, pull request here: https://github.com/WordPress/wordpress-develop/pull/418

Thanks, added some trivial'ish comments to the PR

This ticket was mentioned in Slack in #core by david.baumwald. View the logs.

14 months ago

14 months ago

14 months ago

#24 @whyisjake
14 months ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 48650:

Build/Test Tools: Enable JSDocs to be linted with ESLint.

As part of the [Javascript Inline Docs Initiative](https://make.wordpress.org/core/handbook/docs/inline/js/) this add some tooling to lint Javascript docblocks. Two new commands:

  • npm run lint:jsdoc
  • npm run lint:jsdoc:fix

The latter will run the linter and try to fix an possible issues automatically.

Fixes #43828.
Props netweb, atimmer, kamataryo, whyisjake.

#25 @SergeyBiryukov
14 months ago

In 48651:

Docs: Correct alignment for some parameters in JS documentation.

Follow-up to [48650].

See #43828.

Note: See TracTickets for help on using tickets.