Repository: TypeScript
Issue: Comment inference with type inference
Labels: Suggestion,Awaiting More Feedback

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms

<!--
  💡 Did you know? TypeScript has over 2,000 open suggestions!
  🔎 Please search thoroughly before logging new feature requests as most common ideas already have a proposal in progress.
  The "Common Feature Requests" section of the FAQ lists many popular requests: https://github.com/Microsoft/TypeScript/wiki/FAQ#common-feature-requests

  Replace the text below:
-->

Comment inference, documentation

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
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](https://github.com/Microsoft/TypeScript/wiki/TypeScript-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:

```ts
/**
 * 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:

```ts
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?

```ts
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

<!--
  What do you want to use this for?
  What shortcomings exist with current approaches?
  What workarounds are you using in the meantime?
-->

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.)