Repository navigation
Add JSDOC @module support for intellisense. #30744
Description
Activity
- Reacted by ExE Boss, James, Amber G., tyson and jacobmoshipco
I would like to give this thread a friendly bump to help determine the current status of support plans for this tag. Since we are currently working on stabilizing the experimental module loader API, this knowledge is relevant to the Node.js Modules Team (of which I am an observer) due to its potential as in-band solution for determining a module's format prior to its loading.
If I understand correctly, VS Code uses the TypeScript parser to parse its JavaScript implementation of JSDoc features. In the newest Insiders version of VS Code (possibly older versions as well), the
@moduleJSDoc tag seems to be improperly implemented by the TypeScript parser. This is evident by the incorrect syntax highlighting as can be seen in my screenshot below. Interestingly, the parser from the@typescript-eslint/parserpackage properly detects this as the module type field and provides a warning.
Derived from the official JSDoc page:
@module [ [ { <type> } ] <specifier> ] ]I believe the square brackets mean optional and the parser should not be using that for tokenization.
Relevant links:
- JSDoc - @module
- TypeScript ESLint Parser
- DocumentJS - @module
- LSST DM Developer Guide
- TypeScript - Supported JSDoc
- Node.js ECMAScript Modules
/cc Wesley Wigham (@weswigham) Geoffrey Booth (@GeoffreyBooth)
It would really great if we could enforce a type for a module. A module is similar to an
Objectand the ability to check to ensure a module exports the right types would be extremely useful. For example:/** * @typedef NumberValueModule * @prop {number} value */
goodModule.js:
/** @module {NumberValueModule} piModule */ export const value = 3.14;
badModule.js:
/** @module {NumberValueModule} helloModule */ export const value = 'hello'; // ^ this should be reported as the wrong type
Is this possible at the moment with
typings.d.tssomehow? I would love to start doing this even if it means not using JSDoc yet.This would be very helpful for Node.js functional programmers. Modules should work just like classes, where intellisense infers the type from the code. If you aren't using classes, you are doing double work to define type in the code and then again in JSDoc. It's too easy for these definitions to get out of sync. Please do for modules what was done for classes. Whether based on modules or not, bottom line is to support type inference from code that extends beyond classes to any object or function.
Reacted by Eric BauerfeldReacted by ⊣˚∆˚⊢Please do for modules what was done for classes.
Would you be able to provide a code sample illustrating this? I feel like I'm the only person who uses this convention (even without any tooling benefits). It helps me to keep organized is all.
Reacted by Eric Bauerfeldconnect-stream.js
/** * @param {import('stream').Readable} in * @param {import('stream').Writable} out */ export async function connectStream(in, out) { in.pipe(out) }
detect-fighting.js
/** * @param {import('stream').Readable} lidar * @param {import('stream').Writable} infer * @param {import('./connect-stream').connectStream} cb */ async function detectFighting(lidar, infer, cb) { cb ( lidar.getReadableStream('camera10'), infer.getWritableStream('fighting') ) }
The jsdoc of the 3rd param in
detect-fighting.jsis not supported. You can write xxxx (@callback) but, again, the point is to avoid having to do that and having to keep it in sync with the actual function.
Search Terms
Intellisense jsdoc support for modules
Suggestion
When adding
/** @module moduleName Module Description. */to a module, then doing this:I think it makes sense, when importing the whole namespace, to include the jsdoc
@modulecomment.I also think that when pressing Ctrl+Space for code completion on
"./"(to get a list of modules) should also show the module documentation.Use Cases
Better support for module documentation. I'm developing some module libraries and it would be great to give end users a good experience with better intellisense documentation.
Examples
aModule.ts
app.ts
Checklist
My suggestion meets these guidelines: