JSDoc name conflicts between modules

Each file has its own @module tag at the beginning, so every JSDoc declaration should remain encapsulated inside that file.

However, if I have two type definitions with the same name in different modules, WebStorm stops recognising them or worse, randomly chooses which declaration to use without logic.

6 comments
Comment actions Permalink

Please provide files/code snippets (declarations + usages) that can be used to reproduce the issue

0
Comment actions Permalink

./file-a.js

```

/** @module moduleA */

/**
* @typedef optionsType
* @property {boolean} someFlag
* @property {string} someString
*/

// SOME CODE THAT USES optionsType...

```

./file-b.js

```

/** @module moduleB */

/**
* @typedef optionsType
* @property {number} someNumber
*/

export Class myClass {
/**
* @param {optionsType} options
*/
constructor(options) {
this.options = options;
}
}

```

./file-c.js

```

/** @module moduleC */

/**
* @typedef optionsType
* @property {boolean} someOtherFlag
*/

/**
* @param {optionsType} options // CAN NOT USE cmd+click TO GO TO TYPE DEFINITION. EVEN IF IT IS RIGHT THERE.
*/
export function myFunction(options) {
return options.someOtherFlag;
}


```

./file-d.js

```

/** @module moduleD */

import {myFunction} from './file-b.js';

// WRONG TYPE CHECKING
myFunction({
someOtherFlag: true
});

```

0
Comment actions Permalink

I've found that it might have something to do with classes.

EDIT: Nothing to do with classes. Simply @module scopes are not being respected by WebStorm. JSDoc generated documentation is OK, TypeScript does not complain... It is just WebStorm. Behaviour is buggy/glitchy, seems to happen for some definitions and not for others. Even if they are defined/used in the same way.

0
Comment actions Permalink

Try using the FQ names when declaring/using your typedefs, like:

/** @module moduleB */

/**
* @typedef module:moduleB.optionsType
* @property {number} someNumber
*/

export class myClass {
/**
* @param {module:moduleB.optionsType} options
*/
constructor(options) {
this.options = options;
}
}
/** @module moduleC */

/**
* @typedef module:moduleC.optionsType
* @property {boolean} someOtherFlag
*/

/**
* @param {module:moduleC.optionsType} options // CAN NOT USE cmd+click TO GO TO DEFINITION.
*/
export function myFunction(options) {
return options.someOtherFlag;
}

see https://stackoverflow.com/questions/42829250/jsdoc-reference-typedef-ed-type-from-other-module/42843182, https://github.com/jsdoc/jsdoc/issues/969

0
Comment actions Permalink

I have carefully read all the related information. It is true that there is a serious issue with JSDoc module syntax. However, it has little to do with my current issue.

 

The first link that you provided, addresses how to reference module types from other modules and that is not what I am trying to do. Following module paradigm, every definition should remain encapsulated inside each module. JSDoc module definitions are leaking through different modules.

The second link refers to an issue about how to consume module typedefs inside the same module. Yes, I am not using 'module:my/module' prefix, but that does not justify that WebStorm is randomly using types from other modules instead of warning that the referenced type does not exist. It is a really buggy behaviour and an important issue.

Please take that into consideration.

0
Comment actions Permalink

I've added a comment here: https://github.com/jsdoc/jsdoc/issues/1645  that might be useful for other people.

It is related to the shared links above.

The scope leaking problem of WebStorm remains. Does it make sense that I need full module syntax to make WebStorm understand that I want to use a type from the same module but It perfectly takes types from other modules while using the short syntax? It is almost hilarious.

0

Please sign in to leave a comment.