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.

0
6 comments

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

0
Avatar
Permanently deleted user

./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
Avatar
Permanently deleted user

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

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
Avatar
Permanently deleted user

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
Avatar
Permanently deleted user

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.