Mechanism for libraries to add information to IDE documentation/tooltip

Some folks have asked for things like showing the effective full HTTP route when hovering over an operation. Today, the docs shown on hover are limited to doc comments, @doc, and core language aspects of the entity. Computing the HTTP route is specific to the @cadl-lang/http library so we would need some sort of extensibility here so that the library could provide this data to the IDE.

what if we have some internal decorator/helper that is @ideDoc(

Guess the problem is when do you call that:

in a decorator: might not have the bigger picture yet
in onValidate: you shouldn't modify the graph at this point
a new lifecycle hook? onLsp?

Great point. Maybe if instead of a decorator, we had a dedicated compiler API like addIDEDoc that is explicitly blessed to be safe to call in onValidate?

That's probably clumsy. This isn't "validation".

yeah, would be an "easy" solution but not clean

I think the new lifecycle hook could work.

Maybe we can have something more general in name than onLSP, like onAugment that is generally there to to allow adding additional decorators dynamically. I think this would run first, right after compilation, before validation.

Then a new decorator like @hover that an onAugment handler could add dynamically with a complete picture of the program.

One downside is that I think we're already repeating computation between onValidate and onEmit and we will likely compute the routes a third time for this.

One downside is that I think we're already repeating computation between onValidate and onEmit and we will likely compute the routes a third time for this.

Though it we assume onAugment can change the type graph(which is the point), it probably should be recomputed anyway.

True!

Another possible concern. If I have one lib that uses onAugment to change HTTP routes (which we'd say is OK) and http lib uses it to add route to hover, then there's still a race.

That it a good point, maybe we need some order where you can say you onAugment should run after all the other onAugment

This is bringing back memories of plugin systems that have a "priority" you can return and then someone returns +/- Infinity.

Notes for discussion today

Proof-of-concept: #2116

more general approach
new onAugment added alongside onEmit and onValidate
new @ideDoc decorator
onAugment is generally provided to allow a library to add decorators once an otherwise complete whole view of the world is completed.
runs before onValidate
could have done this in onValidate but 1) this is not validation, 2) what if you want to validate the result of this augmentation.
adds yet another pass (over all routes in HTTP case, other emitters/libs could also end up making more redundant computation)
what if one onAugmnet handler wants to base its decisions on the results of another, how to order them?

Alternative (not implemented):

IDE specific callback to get additional docs for a given entity
e.g. library could register handler somehow for getIDEDocumentation(Program, Type)
solves ordering issues since we no longer need to change the type graph just answer questions about it
but less general purpose
if handled naively could lead to even more redundant work, recomputing all the routes for each hover for example (!)

Summary of discusssion today:

route-in-tooltip not a sufficient motivating feature.
We should not add another phase for this, the costs are too high.
We can either look at the alternative described above or look if we can find a way to have this happen during the decoration phase somehow.

But without a high-pri motivating feature, we can leave this on the backlog.

feat(compiler): add experimental $provideTypeInfo provider and progra…

Navigation Menu

Repository navigation

Mechanism for libraries to add information to IDE documentation/tooltip #1993

Proof-of-concept: #2116

Alternative (not implemented):

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Mechanism for libraries to add information to IDE documentation/tooltip #1993

Description

Activity

timotheeguerin commented on May 31, 2023

nguerrera commented on May 31, 2023

nguerrera commented on May 31, 2023

timotheeguerin commented on May 31, 2023

nguerrera commented on Jun 19, 2023

nguerrera commented on Jun 19, 2023

timotheeguerin commented on Jun 19, 2023

nguerrera commented on Jun 19, 2023

nguerrera commented on Jun 19, 2023

timotheeguerin commented on Jun 20, 2023

nguerrera commented on Jun 20, 2023

nguerrera commented on Jun 26, 2023

Proof-of-concept: #2116

Alternative (not implemented):

nguerrera commented on Jun 26, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions