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.

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

Add prettier JSDoc parser #3832

Closed
wants to merge 4 commits into from
Closed

Add prettier JSDoc parser #3832

wants to merge 4 commits into from

Conversation

renatho
Copy link
Contributor

@renatho renatho commented Dec 9, 2020

This is a PR for documentation purposes of a try

It was a try to add a prettier plugin for JSDoc parser, using this recommended plugin. In the middle of the changes, I gave up because we were having many issues and I think the cost-benefit doesn't worth it.

In summary, some of the errors were:

1) It throws some unhandled errors in some situations, like:

  • TypeError: Cannot read property 'description' of undefined

  • RangeError: Invalid count value

The main problem with these unhandled errors is that if there is any error in a file, it skips the whole file and we can miss files without formatting.

2) It conflicts with a Gutenberg setting.

It prefers @returns and @yields instead of @return and @yield, and there is no option to change that.

3) It forces a misalignment in the descriptions with multiline.

I believe it's a standard that we don't want. It's not explicit in the WP standard documentation, but checking Gutenberg code, it uses the description aligned.

/**
 * How the plugin is forcing the alignment.
 *
 * @param {Object} props Lorem ipsum dolor sit amet consectetur adipiscing elit
 *     sed do eiusmod tempor incididunt ut labore et.
 */
/**
 * How is the standard in the Gutenberg code.
 *
 * @param {Object} props Lorem ipsum dolor sit amet consectetur adipiscing elit
 *                       sed do eiusmod tempor incididunt ut labore et.
 */

4) It removes @since tags when it doesn't have a description.

Future plans for JSDoc lint / prettier in Sensei:

  1. Wait for this refactor in the Comment Parser.
  2. Update/wait for update of the Comment Parser dependency on eslint-plugin-jsdoc.
  3. Update this PR with a refactor to use the Comment Parser.
  4. Update this PR to Gutenberg.
  5. Update the @wordpress/scripts dependency on Sensei and enjoy.
  6. We can also easily write a prettier plugin using the new Comment Parser when item 1 is ready.

It can take a while, but I believe it'll worth it.

@renatho renatho self-assigned this Dec 9, 2020
@renatho renatho closed this Dec 9, 2020
@renatho renatho deleted the add/prettier-jsdoc-parser branch December 9, 2020 17:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant