Comment inference with type inference

Suggestion

🔍 Search Terms

Comment inference, documentation

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• 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.)

Beginnen Sie mit der Überprüfung des bestehenden @inheritdoc-Verhaltens und der Designziele von TypeScript, und verfolgen Sie anschließend, wie inferierte Typen und Dokumentation in der IDE-Unterstützung sichtbar gemacht werden. Da das Issue keine Dateien oder Tests nennt, identifizieren Sie zunächst die relevanten Compiler- und Editor-Pfade, bevor Sie einen Ansatz vorschlagen. Als abgeschlossen gilt die Aufgabe, wenn es eine unterstützte Möglichkeit gibt, Dokumentation für Funktionen zu inferieren, ohne die JavaScript-Laufzeitausgabe zu ändern.