Improve module ergonomics

[hegemonic]

JSDoc users have many well-justified complaints about the way JSDoc supports modules. Those complaints tend to fall into at least one of these categories:

• Syntax compatibility. JSDoc's syntax for modules is not compatible with VS Code/TypeScript/Closure Compiler/(your favorite tool here).

  For example, module longnames must start with module: (for example, module:foo/bar), which other tools don't recognize.

• Code-parsing smarts. JSDoc is not as good as it could be at extracting information from your code.

  For example, suppose the module a.js is documented as module:a and exports the class Foo, and the module b.js does something like const { Foo } = require('a'). JSDoc knows about module:a.Foo, and it knows that module b has a variable named Foo, but it doesn't figure out that they both refer to the same thing.

It would be worthwhile to support some other syntax that's compatible with popular tools (most notably TypeScript and Closure Compiler) and IDEs (most notably VS Code), and to extract more information automatically based on that syntax. We should not invent a new syntax that is incompatible with the rest of the JS/TS universe (contra xkcd). Also, we should continue to support the existing module syntax unless that's absolutely not possible.

Nota bene: Adding support for a different module syntax would almost certainly require large, pervasive changes to JSDoc.

[brettz9]

+1 for TypeScript

[ernestostifano]

I agree that any eventually adopted module syntax should be the most widely compatible. Additionally, I understand that changing the current one could be problematic. However, there is a (hope minor) change that could solve half of the problems.

As mentioned in other issues (#969 and especially #1533), currently, people is forced to use "module:my/module" prefix even inside the same module where types are defined. That is weird and should be addressed independently from the module syntax argument. Please note that current behaviour may not perfectly reflect what stated in the documentation.

All symbols in the file are assumed to be members of the module unless documented otherwise.

Shouldn't this logic apply to assignment statements too?

/** @module myModule */

// DECLARING
/** @typedef {boolean} myType */ // -> Per specs -> module:myModule~myType

// ASSIGNING
/** @const {myType} */ // -> Shouldn't this be implicitly interpreted as -> module:myModule~myType ?
const myConst = true;

If that gets resolved, use cases for the current module syntax would be reduced to the case in which types need to be used across different modules.

And even in that case, additional module syntax might be not needed. Let's also remember that following modules paradigm, anything declared inside a module must remain encapsulated into that module unless explicitly exported. Currently, JSDoc is only abusing the global scope by adding longer names to things (adding the module path).

However, it is interesting to note that the following pattern currently seems to work:

./file-a.js

/** @module moduleA */

/**
* @typedef anyJavascriptContext.myType
* @property {boolean} prop1
*/

const anyJavascriptContext = true;

export {anyJavascriptContext};

./file-b.js

/** @module moduleB */

import {anyJavascriptContext} from './file-a.js'

/**
* @param {anyJavascriptContext.myType} someArg
* @returns {boolean}
*/
function someFunction(someArg) {
    return someArg.prop1;
}

export {someFunction};

WebStorm flawlessly understands it. TypeScript correctly generates declaration files with import/export statements for types while checking above files. ESLint JSDoc plugin does not complain. Seems like the perfect solution right? (The only problem someone could point is that a real JavaScript context is needed to "carry" the type definitions. But returning to the modules paradigm, why should you use a type from a module that you are not importing to be used in some way?). Using namespaces with this pattern works too.

LONG STORY SHORT: I think that #1533 should be fixed right away (I would be glad to help). And current module syntax for cross module types complete abandonment should be considered.

[danielo515]

So typescript import syntax is not yet supported, but is there at least a way to tell the parsers to ignore it?

[wojtek-krysiak]

@danielo515 you can use typedef-imports plugin from better-docs but it will have to be one liner:

/** @typedef {import('./some-other-file').ExportedType} ExportedType */