The intellisense for Foo.js is provided via a corresponding Foo.d.ts only when it’s imported somewhere—in a different file, but not in the Foo.js itself.

[awgv]

• VSCode Version: 1.47.3 (system setup)
• OS Version: Windows_NT x64 10.0.19041

Here’s a contrived directory structure of a React app:

.
└── src
    └── Components
        └── Foo
            ├── Bar
            │   ├── Bar.js
            │   └── Bar.d.ts
            └── Foo.js

// React component `Foo` imports a component `Bar`:

import { Bar } from './Bar/Bar'

export function Foo() {
  //
}

// And gets full intellisense via `Bar.d.ts`:

type Props = {
  /** ... */
}

export declare function Bar(
  props: Props
): React.FunctionComponent

But Bar.js itself doesn’t get intellisense from its own Bar.d.ts file—it’s like the .d.ts doesn’t exist—am I doing something wrong, or is it how it’s supposed to work in the current version of VSCode? I tried the triple-slash directive (/// <reference path="Bar.d.ts"/>), but it didn’t help. Some JSDoc helped, but it’s rather pointless to have a dedicated declaration file and still use JSDoc:

export function Bar(
  // When `type Props` is exported from the `.d.ts`:
  /** @type {import("./Bar").Props} */ props
) {

I tried the Insiders build—same thing. I also prepared a repository representing the example above in case you want to check something yourself. Initially, I asked it as a StackOverflow question (link), but didn’t get an answer, so if you think this is a usage question, please leave an answer there.

[RyanCavanaugh]

This is the intended behavior; there is no supported scenario for "the .d.ts is a sidecar to the .js". The recommended thing to do here is use JS Doc to write your type annotations.

[awgv]

@RyanCavanaugh Hello Ryan, thank you for clearing that up. Will it make sense for TypeScript to support it in the future?

I’ll answer the StackOverflow question, closing the issue as resolved.

[runarberg]

What is the intended way to annotated very complex types that are hard (or even impossible) to express with JSDoc? Examples include extended template types (as opposed to class), variadic tuple types, overloaded functions, etc.

As an example here is a function I’m having difficulty annotating with JSDoc:

// Have to use `@type` rather then `@template`, `@param`, `@returns` etc.
// because `T extends any[]` is not expressible in JSDoc.
/**
 * Take any number of iterators, and zip them together into a iterator
 * of tuples. Closes after the shortest of the inputs closes.
 *
 * @type { <T extends any[]>(...items: { [P in keyof T]: Iterable<T[P]> }) => Iterable<T> }
 */
export default function* zip(...items) {
  const iters = items.map((item) => item[Symbol.iterator]());
  let buffer = iters.map((iter) => iter.next());

  while (!buffer.some(({ done }) => done)) {
    // Ignoring because I can’t access the `T` template defined above.
    // @ts-ignore
    yield buffer.map(({ value }) => value);

    buffer = iters.map((iter) => iter.next());
  }
}

[michaelfig]

// Have to use `@type` rather then `@template`, `@param`, `@returns` etc.
// because `T extends any[]` is not expressible in JSDoc.

@runarberg , have you considered:

/**
 * @template {any[]} T
 * ...
 */