Custom JSDoc type cannot be extended

[almaceleste]

Does this issue occur when all extensions are disabled?: Yes/No

• VS Code Version: 1.99.3
• OS Version: Linux x64 6.11.0-24-generic

Steps to Reproduce:

1. Define a base JSDoc type:

/**
 * @typedef {object} baseType
 * @property {string} baseProperty
 */

2. Define a child type and add a property:

/**
 * @typedef {baseType} childType
 * @property {string} childProperty
 */

Expected behavior: childType has baseProperty from baseType and childProperty from the own definition.

Actual behavior: childType has only baseProperty from baseType.

However, it works in WebStorm:

[sandersn]

That feature is not supported in Typescript. The biggest obstacle to adding it is that @typedef translates to TS type aliases, plus the ability to combine @property tags to create an object type. We need to know what the TS equivalent to a base type would be. Maybe:

type BaseType = { baseProperty: string }
type ChildType = { childProperty: string} & BaseType

But I'm not sure that the proposed version is that much better than making an intermediate type:

/**
 * @typedef {object} baseType
 * @property {string} baseProperty
 */
/**
 * @typedef {baseType} intermediate
 * @property {string} childProperty
 */
/** @typedef {baseType & intermediate} childType */

To move forward with this, we need

1. Good reasons to add the feature.
2. Semantics that map to TS.

that are more substantial than the quick examples I gave above.

[almaceleste]

@sandersn, the first of the suggested examples only works in .ts files.
The second example does not work in .js files, since it is essentially no different from the original code, only more cumbersome.

Perhaps you meant this working example, which I know and use as a workaround because the more compact version in VS Code doesn't work:

/**
 * @typedef {object} baseType
 * @property {string} baseProperty
 */
/**
 * @typedef {object} intermediate  <- {object} instead of {baseType}
 * @property {string} childProperty
 */
/** @typedef {baseType & intermediate} childType */

---

The problem is not that I can't find a workaround to make it work. Because I can.

The problem is much deeper and not as superficial as it seems at first glance.

The problem is that if another developer writes code in an editor in which this JSDос feature works, for example, in the fairly popular WebStorm, then I can't use that code while I'm writing code in VS Code.

And I'm unlikely to be able to convince this developer to write a more cumbersome version so that it works for both him and me, because for any argument I make I'll get a reasonable response to stop using VS Code and start using WebStorm, where everything works fine.

Also, if these typedefs are defined in a third-party library, I won't be able to use them properly without rewriting that library myself, which greatly increases the workload when writing code.

---

Speaking about TypeScript, it is worth noting that this feature has been hanging as requested for many years without changes. #20077

As for JSDoc, if I understand correctly, they refused support & for type intersection, so it's not very clear why TypeScript and VS Code still suggest using & when writing JSDoc comments. jsdoc/jsdoc#1285

[sandersn]

I thought Webstorm's TS and JS support were based on tsserver. Can you specify the webstorm support for this feature in terms of a difference from the base tsserver? That would be the easiest way for us to support it—although because we're unlikely to add more jsdoc features that aren't in TS, I still don't think it would be likely for us to add it.

[almaceleste]

@sandersn, I've passed WebStorm support example for this feature in the OP. I link it hear again:

WebStorm simply supports JSDoc specifications as-is and does not require any workaround.

But in the end, it's not even about WebStorm's support for this feature.

The problem is that VSCode does not support JSDoc specifications.
And if I use the workaround you suggested, which is not supported by JSDoc, I will no longer be able to use JSDoc properly to document my code.
Because if I run jsdoc on a Javascript file containing this workaround I get an error:

$ ./node_modules/.bin/jsdoc typedefs.js 
ERROR: Unable to parse a tag's type expression for source file 
/tmp/test/typedefs.js in line 9 with tag title "typedef" 
and text "{baseType & intermediate} childType": 
Invalid type expression "baseType & intermediate": 
Expected "|" but "&" found.

By refusing to adhere to the JSDoc specifications, you are breaking the very purpose of documenting code through JSDoc comments.

[sandersn]

Perhaps you meant this working example
Yes, that's what I meant, thanks.

Sounds like this is a duplicate of #20077. Should we close this bug in favour of that one?

The two things this needs to start are:

1. A proposal. If JSDoc has a spec for this, that's the ideal starting point. But it needs to have more detail than the example screenshot from Webstorm. For example, what happens when the child type has a property that's the same as the parent? Error if the type is different? Always error? Override the type? Intersect the type?

I looked at jsdoc.app for @typedef and couldn't find this use. That's the site I used back in 2017 to learn JSDoc's semantics. Is there a more complete or up-to-date site?

2. Motivation. How many people actually use this? Memory is unreliable, but I never saw this usage in the dozens of open-source repos I used as examples when developing Typescript's jsdoc features. Of course that's been a long time and I could have missed it at the time.

Afterward, there's still the question of how to implement this in terms of Typescript semantics, but if there's enough demand, we can find a way. (See @type on function declarations for a recent example.)

In the meantime, another workaround could be to put your types into .ts files and add jsdoc comments to type and interface declarations. That's generally how I structure my JS programs, although I don't use the JSDoc generator.

[sandersn]

re the purpose of JSDoc in Typescript: we expect people use jsdoc comments to provide types for consumption by Typescript, mostly, with the text in the comments being consumed in the editor, not on a web page.

Perfect compatibility with jsdoc generators is not our goal, but allowing people to write Typescript in a .js file if they need to.

[almaceleste]

I don't quite understand what you can't find in the JSDoc documentation. The page you linked to (jsdoc.app for @typedef) says the following:

The @typedef tag is useful for documenting custom types, particularly if you wish to refer to them repeatedly. These types can then be used within other tags expecting a type.

That is, you define a type using the @typedef tag, and then use that type just like any other. In fact, there is no fundamental difference between the following two definitions:

/**
 * @typedef {object} firstType
 * @property {string} firstProperty
 */

/**
 * @typedef {firstType} secondType
 * @property {string} secondProperty
 */

You simply use the firstType in the second definition just like the object in the first definition. I don't see that it is somehow forbidden. And the fact that there is no example for this specific case - well, it is impossible to describe all possible cases.

jsdoc utility is needed not so much to view types in a web page, but to generate and update code documentation for further saving in .pdf or .md, for example. You use JSDoc comments when writing code for IntelliSense and can easily generate PDF documentation of your code at any time. I find it useful.

Unfortunately, I don't have the time or energy to do such a deep study of the JSDoc specifications for you right now, especially considering that the result of this work can always be a failure due to insufficiently widespread use of the feature.

Okay, I think that since the previous request has been hanging since 2017 without due attention, it is unlikely that anything will change now.

I just feel bad that my beloved VSCode is increasingly moving away from the specs, making it harder to use. You take existing technologies with their own specs and use them as you want, without paying attention to whether it breaks the original functionality.

Let me clarify. I am not trying to offend anyone. I do not wish to generate negativity. I am simply stating the situation.