TS8040: A JSDoc '@type' tag may not occur with a '@param' or '@returns' tag.

[JakobJingleheimer]

Steps to reproduce

/**
 * @typedef {object} AliasInitConfig
 * @prop {`file://${string}`} AliasInitConfig.location The name or fully resolved location of the tsconfig.
 */
/**
 * @type {import('node:module').InitializeHook}
 * @param {AliasInitConfig} [config] Configuration object to customise Alias loader.
 */
function initialiseAlias(config) {
}

Behavior with typescript@5.8

It works fine

Behavior with tsgo

It (incorrectly) errors

---

Possibly fixed by #1960 (description looks kinda related).

[jakebailey]

That PR was released in the most recent nightly. What version are you testing with?

But, I'm pretty sure this error is correct? You're simultaneously annotating the function with @type and also @param. You can omit one of those and it should be fine...

[JakobJingleheimer]

What version are you testing with?

7.0.0-dev.20251027.1

You're simultaneously annotating the function with @type and also @param. You can omit one of those and it should be fine...

No, which is precisely why it's there 😜 @type applies the over-all type and @param applies a specific override; this also works in typescript itself, like

const foo: SomeFunctionDef = (bar: SomeOverride, qux) => {};

everything about foo gets its type from SomeFunctionDef except the first argument bar, which is overridden as SomeOverride.

[a-tarasyuk]

typescript-go/internal/diagnostics/extraDiagnosticMessages.json

Lines 18 to 25 in 4037f3a

	"A JSDoc '@type' tag on a function must have a signature with the correct number of arguments.": {
	"category": "Error",
	"code": 8030
	},
	"A JSDoc '@type' tag may not occur with a '@param' or '@returns' tag.": {
	"category": "Error",
	"code": 8040
	},

Strada doesn’t have these diagnostics — this changes part of #1468. So I suppose the #1960 doesn’t resolve it

[JakobJingleheimer]

I think the fix is simple then—just be deleted them? I'm not sure why they were added 🤔

[ahejlsberg]

I think the fix is simple then—just be deleted them? I'm not sure why they were added 🤔

It's not that simple. It so happened to work in Strada, though I don't think it was ever intended. Corsa resolves @type and @param annotation differently than Strada, effectively making them equals instead of having one (unintentionally) override the other, so I don't see us supporting this pattern.

[JakobJingleheimer]

It so happened to work in Strada, though I don't think it was ever intended.

It's worked for years in various tooling with JSDoc, so "not intended" doesn't sound accurate. I don't know what Corsa is—I'm guessing it's a dependency of tsgo (whereas Strada was a dep of tsc?). If so, history and the official JSDoc docs for @type say that implementation is wrong:

You can also include type expressions with many other JSDoc tags, such as the @param tag.

[jakebailey]

(Strada was TypeScript's codename, Corsa is the Go port's codename)

[ahejlsberg]

Did a bit more experimenting. I thought the intent in your example was to have @param type annotations override the parameter types specified in @type, but that doesn't appear to ever have worked. In Strada, the types specified in @type win and the types (if any) specified in @param are ignored (even if they disagree!). But the combination does allow you to independently document the parameters, and we do indeed display that documentation in Quick Info.

So, the new behavior of disallowing combinations is probably too draconian. I'll put up a PR that aligns us with the old behavior.

[ahejlsberg]

Hmm, so what's really happening in Strada is that @type controls the signature used for calling the function, but @param controls the type for the parameter in the function body. So it basically amounts to an unchecked type cast (which easily could be wrong). I'm not in love with that, but then again, overloads aren't really checked strictly either.

[jakebailey]

Is there a middle ground that works like the TS as written in #1970 (comment)? Then we'd be better off than we were before.

[ahejlsberg]

Is there a middle ground that works like the TS as written in #1970 (comment)? Then we'd be better off than we were before.

That would require switching @type to be processed like a contextual type, which isn't something we do for function declarations (we only do for function expressions and arrow functions). So, we'd need a whole new form of signature merging just to support this "feature". Which then would need to be back-ported to Strada.

[ahejlsberg]

Honestly, I think this is just one of these oddities of JSDoc that we should leave alone--and move along.

[ahejlsberg]

@JakobJingleheimer I should mention that the pattern in the repro is likely not working the way you assume. The @param tag only changes the type of config in the function body. It doesn't change the parameter type in the signature of the function. And since InitializeHook declares the parameter to be of type any, you can still call the function with an argument of any type. Basically an accident waiting to happen.