Add JSDoc ESLint script

[netweb]

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:

• Gutenberg References: ​6341 ​4506 ​4504 ​4245

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

[atimmer]

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?

[netweb]

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

[jorbin]

Bumping this from 5.2 due to lack of progress

[kamataryo]

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

[kamataryo]

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

[kamataryo]

Fixed the broken patch 43828.2.dff

[kamataryo]

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

[kamataryo]

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

[netweb]

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

[netweb]

Punting this to 5.4 to help clear the 5.3 milestone

[netweb]

Punting this to 5.5 to help clear the 5.4 milestone

[whyisjake]

Patch updated @netweb, seems to be working fine.

[netweb]

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

​https://github.com/WordPress/gutenberg/blob/master/packages/eslint-plugin/configs/jsdoc.js

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

[whyisjake]

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.

[netweb]

@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

@@ -837 +837 @@
 
                                 if ( $original_object ) {
                                         $menu_item->url = get_permalink( $original_object->ID );
-                                        /** This filter is documented in wp-includes/post-template.php */
-                                        $original_title = apply_filters( 'the_title', $original_object->post_title, $original_object->ID );
                                 } else {
                                         $menu_item->url      = '';
-                                        $original_title      = '';
                                         $menu_item->_invalid = true;
                                 }
 
-                                if ( '' === $original_title ) {
-                                        /* translators: %d: ID of a post. */
-                                        $original_title = sprintf( __( '#%d (no title)' ), $menu_item->object_id );
-                                }
+                                $menu_item->title = $menu_item->post_title;
 
-                                $menu_item->title = ( '' === $menu_item->post_title ) ? $original_title : $menu_item->post_title;
-
                         } elseif ( 'post_type_archive' === $menu_item->type ) {
                                 $object = get_post_type_object( $menu_item->object );
                                 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?

[whyisjake]

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

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

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

[whyisjake]

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

[netweb]

Replying to whyisjake:

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

Thanks, added some trivial'ish comments to the PR

[whyisjake]

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.

[SergeyBiryukov]

In 48651:

Docs: Correct alignment for some parameters in JS documentation.

Follow-up to [48650].

See #43828.

Merged into WP Core in https://core.trac.wordpress.org/changeset/48650