Comment inference with type inference

[mindplay-dk]

Suggestion

🔍 Search Terms

Comment inference, documentation

✅ Viability Checklist

My suggestion meets these guidelines:

• [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
• [x] This wouldn't change the runtime behavior of existing JavaScript code
• [x] This could be implemented without emitting different JS based on the types of the expressions
• [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• [x] This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Infer documentation/comments for inferred types.

📃 Motivating Example

I heavily use functions with dependency injection - this frequently means having a unit version of a function, as well as a convenience version with some of the arguments already applied.

For example, let's say I have a function:

/**
 * Great documentation here!
 */
function cook(food: Food, spices: Spice[], pot: Pot, pan: Pan) {
  // ...
}

I might have lots of functions like these, all of them may have different dependencies.

Somewhere in the top layers of my application, I'm going to bootstrap my function dependencies using functional applications:

function bootstrap(pot: Pot, pan: Pan) {
  return {
    cook: (food: Food, spices: Spice[]) => cook(food, spices, pot, pan),
    cleanUp: () => cleanUp(pot, pans),
    // ...and so on...
  }
}

The problem here is, the documentation for the original function is lost.

I don't want to copy/paste all my documentation and maintain several copies. So I'm left with the choice of leaving the internal unit function undocumented, and explicitly writing out an interface for the bootstrap return-type, giving up the convenience of inference - or leaving the bootstrapped functions undocumented.

There aren't really good choices.

Could we have something like this maybe?

function bootstrap(pot: Pot, pan: Pan) {
  return {
    /** @inferdoc */
    cook: (food: Food, spices: Spice[]) => cook(food, spices, pot, pan),
    /** @inferdoc */
    cleanUp: () => cleanUp(pot, pans),
  }
}

This would follow the inferred type to it's type and infer (copy) the documentation from there.

We have something like this for classes with @inheritdoc, but nothing for functions.

💻 Use Cases

Everything. 😄

I don't know of any work-arounds - I would love to hear of any.

IDE support is crucial here. Not repeating documentation is important. Inference is important - I don't want repeated declarations. I'm already repeating the argument declarations, which isn't great, but I don't think there's any way around that? (It's possible the real issue here is that we need stronger inference for function types? Something that works better for very common patterns like functional applications? Might kill two birds with one stone.)

[MartinJohns]

Related: #32392