unjs
feat: support for JSDoc extraction
This PR aims to extend the auto import process to allow for automatic JSDoc extraction for better in-IDE documentation. Initially thought of using for nuxt, I figured this might benefit all tools that may use unimport.
I am marking this as draft for now, until I make sure it all works well, since a couple issues have risen from my initial testing. Also, yes, I know my code isn't the best, as this is the prototype version. Any constructive criticism and suggestions for improvement are appreciated!
Marking this as ready for review after all testing I could do was done, would appreciate feedback!
I migrated from TypeScript, in stead I used regex patterns, but this was a big change so I may or may not have broken something. Would appreciate feedback! It seems to work on my local machine for any exposed function (and const) with a valid JSDoc annotation.
@antfu sorry for being impatient, but is there any updates on this? I do think this will greatly improve overall DX.
@danielroe I forgot to ask, should I make a test case for this? I'm not the best at writing tests (in fact, I have never done it) but I can certainly try if it's needed, I'm just not sure what the conditions for writing tests are.
I think, in general, the quality of this PR does not match the standard:
- Hard-coded specific handling (despite the review comment, the issue still presets)
- The solution seems to be quite hacky (relies on conventions rather than a proper resolving algorithm)
- There are no tests to guarantee how it would work.
- It doesn't follow the repo's linting and formatting rules.
I am sorry for taking long to respond. I think the feature itself is legit and would indeed benefit the DX if we implement it well. However, we would need time to think of a more robust solution.
There is a slight issue. I don't think there's a way to make this more framework agnostic, mainly because of the existent changes between framework. Yes, this is based on conventions, and yes, it's not really agnostic. But it's reliable, and it catches all the edge cases. How would you go about making it not rely on conventions?
Attempt number 3, I have completely reworked the way I handle this, and now I am utilizing map and reading the files to rely as little as possible on conventions. When the file isn't found through package.json it checks all extension, otherwise will just return null. Would love to hear your opinion!
Sorry i will try to be back on this as soon as I can (probably next week, sorry again).
For the digest, we have talked with @antfu and @GalacticHypernova to use of an AST parser to extract JSDocs. untyped already exposes a bundled AST parser as well as tools that allow this. However thinking more, since mlly also plans to switch to AST parsers (https://github.com/unjs/mlly/issues/219) + the fact that we probably don't want to make users (of all these packages) have multiple versions of AST parser, I think probably best course of action would be wait for AST switch in mlly + try to use babel parser (which supports TypeScript) or untyped for making a full proof on concept here in this PR.
Alternatives that probably not work:
- Regexp: Lots of edge cases
- TS Server: Huge dependency and also lacks support for just giving JSDocs even if wan to
- Acorn parser: ESM Only no typescript support
- Wasm parser: Nice (and something I aim to universally migrate to across UnJS) but probably to early and risky for this POC because it can cause diversion and installing native dep is tricky specially if multiple packages do it.
