docs: JSDoc overhaul

[GalacticHypernova]

🔗 Linked issue

Haven't found anyone really mentioning anything about it

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Similar to the grammar overhaul (#20636), this PR includes a JSDoc overhaul (and in this case addition) to many Nuxt functions for better in-IDE documentation.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[danielroe]

This is great! It would be good to ensure we sync the language between API documentation and the inline JSdoc comments. I also hope we can do this automatically - is that something you have interest in or should I implement separately?

[GalacticHypernova]

I'd love to help as much as I can!

[GalacticHypernova]

I was also thinking of changing the prepare:types hook to not override JSDoc annotations there, so that it could also be synced automatically as well, however for that I'll need a little more time to look into the internals of Nuxt.

[GalacticHypernova]

Also I am not entirely sure why, but it doesn't register the commits I am making to the patch-8 branch for some reason... Probably GitHub having some issues again.

[GalacticHypernova]

Now it did 👍

[GalacticHypernova]

@danielroe so what would be the best way to go about it? I thought how since all constants get overridden (when I was testing the JSDoc) we can override them with additions from a separate file that will have all JSDoc contents, and for all the functions like in router.ts I don't mind writing the JSdoc manually as it isn't overridden.

[GalacticHypernova]

@danielroe Could you please direct me to where in the packages nuxt overrides .nuxt/types/imports.d.ts? I have the general idea of how to make this work, I just want to make sure I do it at the right place so I won't mess anything up.
Update: Found it!

[GalacticHypernova]

It seems like the only reliable way is by modifying unimport, unless I have no idea what I'm talking about in which case I'd appreciate being corrected. If I am right, it can easily be solved by just adding a nuxt-specific implementation that also has another property called JSDocLoc which we can provide to the part of the JSDoc file. Let me know what you think about this approach! (Of course we can rename and implement it differently, that's just my initial idea)

[GalacticHypernova]

If only the file didn't self destruct in the IDE... Do you by any chance know where I can access and modify that file on my machine before actually trying to push a commit?

[GalacticHypernova]

Update: found the file in the IDE, managed to modify the const imports. Will try to make something work, currently thinking of just having a file with all the JSDoc and then reference it from there. Please do let me know if you have any better solution, would love to hear it!

[GalacticHypernova]

Another update (so sorry for spamming, I'm just very eager to make this work):
We can change the unimport file to something like:

function toTypeDeclarationItems(imports, options) {
  return imports.map((i) => {
    const from = (options?.resolvePath?.(i) || i.from).replace(/\.ts$/, "");
    return `${JSDoc[i.as]}\n\tconst ${i.as}: typeof import('${from}')${i.name !== "*" ? `['${i.name}']` : ""}`;
  }).sort();
}

(Notice the JSDoc[i.as] at the beginning, that will load the JSDoc for each const)

But wouldn't that still require manual addition? Until we make it grab it automatically?
The bigger issue would be to grab it automatically from so many other dependencies as sometimes they don't even have their own JSDoc, so I don't mind writing the JSDoc myself and adding it to the file, if you think this is a reasonable solution.

[GalacticHypernova]

I think the reason a lot of the nuxt constants don't get the JSDoc (like navigateTo) is because of the way they're exported (i.e export { function1, function2... } from 'location') so I have a feeling that's why the constants don't get the JSDoc despite the actual declared function having it, because whenever you treat it like a function and add parentheses the JSDoc loads up. I don't know if it would be a good idea to rework how Nuxt exports all the globally available functions, would love your opinion on it!

[GalacticHypernova]

@danielroe Coming back to this, for features that are explained on MDN (like navigateTo's WindowOpenFeatures) should I provide a minimal explanation and a link to the corresponding resource in MDN, or just provide the link?

[luc122c]

This is great! Please also see #24950 (comment). There may be some crossover between this PR and the work I've been doing. The end goal is the same, better documentation and intellisense, but there may be some merge conflicts along the way.