Add JSDOC @module support for intellisense.

[rjamesnw]

Search Terms

Intellisense jsdoc support for modules

Suggestion

When adding /** @module moduleName Module Description. */ to a module, then doing this:

import * as myName from "./moduleName";

I think it makes sense, when importing the whole namespace, to include the jsdoc @module comment.

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

`/** @module aModule Does something awesome. */`

app.ts

import * as aModule from "./aModule";
// (moduleName should both have the doc details)
// ("./{*.*}" - all files in code completion should show the documentation as well)

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[borekb]

Also, quite annoyingly, the module doc comment is shown for the first member:

Playground link

[DerekNonGeneric]

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 @module JSDoc 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/parser package 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 @weswigham @GeoffreyBooth

[clshortfuse]

It would really great if we could enforce a type for a module. A module is similar to an Object and 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.ts somehow? I would love to start doing this even if it means not using JSDoc yet.

[tysonrm]

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.

[DerekNonGeneric]

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.

[tysonrm]

connect-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.js is not supported. You can write @callback but, again, the point is to avoid having to do that and having to keep it in sync with the actual function.