Repository navigation
API for showing additional info in a hover #195394
Description
Activity
Hi Jake Bailey (@jakebailey) Matt Bierner (@mjbvz), we have discussed this issue in the team and I see three possible ways to implement this:
(1) We can propose a new API
provideExtendedHoverwhich would have the same signature as the existingprovideHover, and would be called when the user requests more detailed hover information. The extended hover information will entirely replace the previous hover information. The downside of this method, is that we have no way to enforce that the new hover information will in fact be an extension of the initial hover information, as one could return any random markdown string through this method. A variant of this method could be to instead add a boolean in the signature ofprovideHoverto signal that one wants extended hover information.(2) Instead we could change the class
Hoverwhich is returned byprovideHover, so that it has one more fieldadditionalContents: MarkdownString. TheadditionalContentsmarkdown string would be displayed below the current hover when the user requests more information. The disadvantage of this approach is that one can not replace the whole current hover information with something new, since the new information is instead appended at the end on request. The other potential disadvantage of this method is that all the extended hover information will be shown at once, so the user can not target what extended information to show exactly. The advantage however is that this approach is simple.(3. a) Another idea that was discussed by our team is the following. We could allow extension authors to return hover markdown information with custom URI links. On click of this custom link, we would do a request to the hover provider through a proposed API
resolveLinkthat would return a markdown string that would either replace the original link or be appended at the end of the hover (to be discussed still). In other words, the flow would be as follows:- In a hover markdown string that contains
FooBaras an expandable type, the TS team could encloseFooBarin a link - On click or hover of this link (to be discussed), we would send the following request:
const link = CustomUri('FooBar', opts); const res : MarkdownString = hoverProvider.resolveLink(link);- The result
reswill either replace the custom uri in the hover, or be appended to the bottom of the current hover.
This idea would require us to introduce a new proposed API
resolveLink. The advantage of this idea is that the user can decide what information exactly to expand (perhaps the user does not want all the expanded information). This puts however more work on the extension authors.(3.b) We have also discussed another variant of 3.a. The flow is as follows:
- In a hover markdown string that contains
FooBaras an expandable type, the TS team could encloseFooBarin a custom link as follows:
const x : [FooBar](file://c/:/myworkspace/FooBar.ts#L250C33)- On click or hover of this link (to be discussed), the controller would use the associated link to fire a hover request for the file
file://c/:/myworkspace/Hello.tsat line 250, column 33. - The result will be displayed at the bottom of the current hover.
In the case of TypeScript, the link will point to the definition of
FooBar. This idea is simpler in that it does not require to manually process links through the implementation of anresolveLinkAPI. The disadvantage of this method however is that the extension author needs to define the appropriate link in the custom URI, and can not add more information then what is otherwise requested.Please let us know what approach you think is more appropriate and what would suit better the needs of the TypeScript team. Thank you.
cc Johannes Rieken (@jrieken) Henning Dieterichs (@hediet) Martin Aeschlimann (@aeschli) Ulugbek Abdullaev (@ulugbekna)
- In a hover markdown string that contains
Thanks Aiday Marlen Kyzy (@aiday-mar)! Either 1 or 2 sound fairly easy and I think would address the original request
I personally prefer approach 1 where we pass a boolean or enum to
provideHoveras I think this will be the easiest to adopt and fully replacing the hover gives us a lot of flexibilityHowever if we go with approach 1, we'd also likely want a way to figure out a way for providers to tell us if they can provide extended info or not. That way we can show an
expandbutton in normal hovers. Maybe we could add a newisExpandablefield onvscode.Hover?Ryan Cavanaugh (@RyanCavanaugh) Daniel Rosenwasser (@DanielRosenwasser) What do you think about these proposals?
Approach 3 is interesting and something that we've talked about before for improving our diagnostics UX. I especially like that it could let us support
go to definitionand other language features in hovers. However it will also be much more complicated to implement in VS Code and for extensions, so I'm sure if we're ready to start down that road right nowOne nice feature of approach 1 or 2 is that we could implement 3 on top of them later too
Reacted by Aiday Marlen Kyzy and Ryan CavanaughWith (2). couldn't
additionalContents: MarkdownStringbe optional?
with theexpanded infobutton based off, ifadditionalContentsis present or notReacted by Aiday Marlen KyzyTo discuss (raw notes):
proposal 4: the hover provider returns an URI which is then interpreted as a text document and rendered in the hover. This allows us to invoke the DocumentLinkProvider on that document.
proposal 5: the hover provider returns another field (annotations) which references offsets into the markdown content. Via annotations we could link to locations (similar to proposal 3b). It could be another field in the Hover or it could be MarkdownStringWithAnnotations.
I have discussed the proposals in #195394 (comment) with Alexandru Dima (@alexdima). Conclusions from the discussion are as follows:
- Solution 1 allows users to return any markdown string in the method
provideExtendedHoverwhich would break the contract of returning only extended information. - Solution 3.a and 3.b imply we would use custom links (like command links) in Markdown code blocks which are currently not supported. To implement these proposals, we would need therefore to do some pre-processing or post-processing of the content to turn it into a proper Markdown string. This implies deviating from standard Markdown in the content hover which is not ideal.
2 more proposals have been made in the comment #195394 (comment) above. I have scheduled a meeting to discuss this work further.
- Solution 1 allows users to return any markdown string in the method
- Solution 1 allows users to return any markdown string in the method
provideExtendedHoverwhich would break the contract of returning only extended information.
Why is this a concern? Why would anyone put completely different info into a hover tooltip? That seems like it would not be productive for any API consumer (and one could totally "misuse" any other feature for other uses already?).
- Solution 1 allows users to return any markdown string in the method
Indeed that would not be productive for any API consumer. The idea is to limit this possibility of this happening.
I will bring up this thread in our meeting and let you know of the discussion later.
Hey all. We have discussed all of the proposals in a meeting, and decided to move forward with proposal 1, since it seems to be what best suits the needs of the TypeScript team. We will put proposal 5 on the backlog, and potentially implement it in the future too, since proposal 1 can co-exist with proposal 5.
To give more detail about the implementation, extensions will be able to return a hover with additional fields
currentZoomLevel,canZoomOut,canZoomIn(names are yet to be refined). On request of a zoom in, or zoom out, requests will be made through the provideHover method (which will have an additional parameterzoomLevel) for hover results. Extensions will thus be able to provide gradually more and more information on zoom in.Reacted by maxpajRelated?: #64566, #94679, microsoft/TypeScript#35601
Any progress, or projection when we can expect to have it released?
Hi clcoco so this PR will likely be part of VS Code 1.89, but not 1.88
Reacted by Mostafa AbobakrFixed with #210472
Reacted by Pedro Américo- locked and limited conversation to collaborators
on Jun 11, 2024 In the last UX sync, Gabriela Araujo Britto (@gabritto) who is currently working on adopting the expandable hover for TypeScript, mentioned the TypeScript team would like to add links in the hover which when clicked would expand the specific type. There are several reasons for this:
- There could be many types in a hover, and it would be nice if the user could expand a specific type not the whole text all at once
- The hover would be smaller
The hover is a nice way to display the types because it is easily discoverable and can be used to easily expand and contract type information. In the UX sync certain other ideas have been proposed for how to display the type information:
- Add an action to the status bar called for example
Inspect Typeswhich would open up a view where the types could be shown.- We could show the peek view with the type definitions
- Or the explorer view with the type information
- Another idea was to allow 1 to 2 levels of expansion only with the current UI then move to the explorer view
We should discuss this other language extensions authors and collect more feedback to see if/how much they would find it useful to have expandable links in the hover.
Problem
For TS, one of our most popular feature requests is showing expanded type information in hovers. For example, with the code:
Hovering over
footoday showsFooType. While this is sometimes what you want, other times you'd like to see the type expanded tostring | numberinsteadWhile we could add a global setting for expanding types in hovers, this isn't a great solution as sometimes the expanded type is very confusing. Really we want to provide both the simplified and expanded hover info and make it easy to switch between them
Feature Request
Add new UI and apis that users to request a more detailed version of a hover. The user action for this could be:
We believe that other languages besides typescript could use this functionality as well. Jake Bailey (@jakebailey) brought up Python for example but C++, c#, and any other languages with complex types could likely benefit