Skip to content

Comment inference with type inferenceΒ #43847

Open
@mindplay-dk

Description

@mindplay-dk

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.)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Awaiting More FeedbackThis means we'd like to hear from more people who would be helped by this featureSuggestionAn idea for TypeScript

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions