Include route information when user hovers on the generated doc

Allen Zhang (@allenjzhang)

Clear and concise description of the problem

When user hovers on some element in the generated doc, he can see the route information about how the element is generated from typespec.

We would need compiler and emitter support to provide the route information to show in ide. Allen Zhang (@allenjzhang) will provide more detail about this feature and design.

Checklist

Follow our Code of Conduct
Read the docs.
Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Duo of #1993
This needs design in the compiler library api

Per #1993, more accurately, it is an ask of including the effective full HTTP route when hovering over an operation.

Timothee Guerin (@timotheeguerin)

Timothee Guerin (@timotheeguerin) , Allen Zhang (@allenjzhang) , the #1993 is like more than one year ago. Do we have more update/design discussion on it recently?

And in my opinion, the feature request here is very specific for HTTP route though we want to have a general solution for it. But if we think about the request more generally. I think what our customers want is to be able to view the typespec and the final outcome together in some way easily. Then how about solving this request by support side-by-side preview? so instead of hovering, when user selects an element, he can view the output on the right clearly and easily which would cover either the route info or anything else he's interested? I think in this way

our customer can view route info or any other related info easily side-by-side. And I believe this would further benefit more customers in much broader user scenarios.
our emitter only needs to generate mapping file (one time effort); they don't need to keep making change and adding info into hover when there are more stuffs user wants to view
our compiler is clean.
of course, the side-by-side preview would need support of mapping file which may need some cost. I am not sure. But to be honest, I think we will need to support side-by-side preview sooner or later anyway.
So let me know how you think about it. Or maybe PM can also help to validate which feature our customers would prefer. thanks.

If we can get the side by side preview of input to output(again needs to be generic to workin the IDE, cannot make any assumption that they want openapi3) then that also would be pretty awesome but I think that is a lot more work.

For the design we don't have anything finalized. What I was thinking is providing the following a library could define

export const $hooks = defineHooks({
  // This would get called by the lsp when hovering a type for example
   info: (type: Type) => {
    return // some estabnlished structured info information that the lsp in turn can display
  },

  // This is for library/emtiter author to help in the playground(Though we could maybe integrate in lsp too)
  inspect(type: Type) => {
    return {
      pagingInfo: () => ... // return paging info data by calling paging info helper 
   } 
  }


})

yeah, I guess that would have higher cost. Just think if the side-by-side preview feature can meet our customers' needs (also more general and benefit in my opinion) and we need to do it anyway sooner or later, then maybe we can save the cost for this one and make it in one step.

About the design you shared. I am not quite sure I understand it correctly. Do you mean lsp would need to iterate each emitters/lib in the project and then call info() on each to get things to show for hovering? Then how would the emitters/lib get these info without compiling? I think these information needs to be figured out when compiling (or emitting) isn't it? And would it cause some perf issue if we call it separated for each emitter/lib, like compilation is triggered (somehow) multiple times?

and some other idea, how about handle it like the diagnostics? (it's like diagnostic whose severity level is "information" from some point of view..) for example, when compiling, emitters can report these info as Info level diagnostic (or a separated typespec_diagnostics if we dont want them included in the existing diagnostic system), then IDE can retrieve all these typespec_diagnostics in one compilation and somehow parse and show them as contracted

No we still only compile one, same as we do when you hover now it compiles and calls getDoc and a bunch of the compiled program state. Here additionally it would go for registered hooks and call them.
The reason its better this way vs returning it all, 1 you don't need to compute it all upfront if it might be a little expensive(could even make the hook async) for the inspect hook it would be even more relevant as it would potentially call expensive internal functions

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

Navigation Menu

Repository navigation

Include route information when user hovers on the generated doc #4860

Clear and concise description of the problem

Checklist

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Include route information when user hovers on the generated doc #4860

Description

Clear and concise description of the problem

Checklist

Activity

timotheeguerin commented on Oct 25, 2024

josefree commented on Oct 29, 2024

RodgeFu commented on Oct 29, 2024

timotheeguerin commented on Oct 29, 2024

RodgeFu commented on Oct 31, 2024

timotheeguerin commented on Oct 31, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions