fix(semantic): Refactor jsdoc finding

[leaysgur]

Partial fix for #168

• Fix general finding behavior for leading comments
• Accept multiple jsdoc comments per node
• Provide get_one and also get_all
• Add iter_all() for non-node related usage
• Limit AST node kinds to parse

[Boshen]

Thank you so much for trying to implement one of the hardest part of this project ❤️

You are free to rewrite everything if you think it's necessary. What I wrote is just a prototype to initiate eslint-plugin-jsdoc.

You have write permission, you may try graphite with stacked PRs.

[codspeed-hq]

CodSpeed Performance Report

Merging #2437 will not alter performance

_{Comparing jsdoc-parse (cd575d8) with main (6aa8c2d)}

Summary

✅ 27 untouched benchmarks

[leaysgur]

one of the hardest part of this project

This is so true! 😂 The more I looked into it, the more I got confused...

Although there are many usecases for JSDoc comments and also implementations(I've learned JSDoc TS, jsdoc.app, eslint-plugin-jsdoc are all differently implemented 🫠), if we set primary goal to implement eslint-plugin-jsdoc, I'm going to try to identify again what kind of API are needed.

[Boshen]

Yeah the first goal is to get eslint-plugin-jsdoc tests passing. jsdoc doesn't have a formal spec so it's a bit hard to figure out which implementation to go for.

By looking at the dependencies of eslint-plugin-jsdoc, I think we can split the task into:

• jsdoc comment parsing - https://www.npmjs.com/package/comment-parser
• find the rules of jsdoc comment attachment

[leaysgur]

Thank you so much~! I'm just now deciphering that code base... 🕵🏻‍♂️
(Sorry the PR is still half done.)

[Boshen]

Feels like I can merge this as is after looking at the code.

[leaysgur]

There are a few things I want to fix here.

• Decide how to handle (): ParenthesizedExpression
  • jsdoccomment does not attach JSDoc to this, but TS does(and this is intuitive tho)
• Return the nearest comment only or split API for this
  • Still keeping them in array
• Note about min, maxLines settings does not supported
  • jsdoccomment and eslint-plugin-jsdoc has options for this
  • Blank lines are configurable between a node and its attached JSDoc
    • e.g. if 2 lines are open, do not attach.
    • e.g. Ignore it if on the same line
    • (I'm not sure what this for...?)
• Collect all non-attached JSDoc, in particular, those located at the EOF and not attached to any node

(Of course, feel free to merge first. I'll send a PR for this later.)

[Boshen]

Thank you so much for working on this, we'll get there eventually 😁

It seems like we're a little bit closer to https://github.com/import-js/eslint-plugin-import/blob/v2.29.1/docs/rules/no-deprecated.md

Let me setup the code for it.

[leaysgur]

Oh, JSDoc everywhere! 😮

Now I can understand this kind of things easily...

• eslint.sourceCode#getCommentsBefore()
  • https://github.com/import-js/eslint-plugin-import/blob/ee5fadeffff68f2300bed7f67a310496cb969d61/src/ExportMap.js#L224
• doctorine.parse()
  • https://github.com/import-js/eslint-plugin-import/blob/ee5fadeffff68f2300bed7f67a310496cb969d61/src/ExportMap.js#L263

Wish you luck. 🚀