IntelliSense text doesn’t wrap / gets cut off

[dstorey]

The IntelliSense text hint (at least in CSS) is a single line, so often a lot of the text description and browser support gets cut off.

It would be nicer to either allow the text to wrap, show the full text on hover/focus, or make the text more concise so important info is less likely to get cropped.

Perhaps the browser support info should be cleared to the next line to make it less likely to be cropped?

[jel-massih]

The way the tree layout works, individual item heights are expected to be explicitly specified pre-render (at least from my understanding of it.) And as that's shared across the UI, wordwrap may not be the way to go.

I did a super janky wordwrap implementation in the commit above (using arbitrary height calculation so its pretty cringey)

[jel-massih]

What about doing something like Visual Studio where it opens a panel to the side? If the text would take up more than one line we can render it to a side panel.

[joaomoreno]

@jel-massih 💯% correct about the tree layout mechanism. I would hate to do an extra panel though, just feels ugly... would be great to get more ideas here.

[jel-massih]

How about the description autoscrolls from beginning to end. Thinking something similar to music players when the song name is long. When an entry is selected, after ~2 seconds or so it will start scrolling to the left to show clipped text. Once it reaches the end it stops for 2 seconds and resets.

I'll poke around a bit with it tommorow to get a prototype mocked up if theres no objections/better ideas

[cknightdevelopment]

I personally like the way that is looks visually here, and would not really be a big fan of the auto-scrolling. I know you mentioned that the temporary implementation you had in place was "jankey" and "cringey", but I really do like the way that it looks in the UI! Is there a way to make the implementation dynamic? What are your thoughts?

[dstorey]

What if the text was restricted to two lines (so it keeps the consistent current layout where things don't move around when moving through items...all items under the selected one don't get moved down or up)? Or instead of two lines, 140 characters, which is probably approx. the same length. It would require rewriting of some of the descriptions to get under that limit, but there could be some improvements in consistency anyway. I'm not sure if the text is used elsewhere though? (probably Visual Studio? and Mad’s VS Essentials web site?)

If the text length is restricted, it would be nice to move the browser support info out of the description string. It is already stored separately in the XML. It could perhaps be shown to the right of the property name if there is enough room (perhaps only for the selected item still to avoid visual noise.)

Otherwise perhaps the text could just get expanded on hover, but that wouldn't work for touch devices, and would need to be careful it can still be read by screen readers.

[jel-massih]

@dstorey So if the description only has one lines worth of text the second line would just be blank?

I do like the consistency as its not jumping around like with variable length wordwrap.

For the expansion on hover, do you mean like a little mouse tooltip bubble type thing or something different?

[Sevin777]

I have a lot of thoughts about this. I wrote a lot of details about it, the top section has my conclusions and below that is how I got to the conclusions:

---

Conclusions

• The only way to properly display the full comments (assuming these are either comments parsed from code or documentation from a static source) is to use a separate window. The comments must support displaying whitespace (line-breaks at the very least) from their source, otherwise Monaco is going to be ignoring existing standards (example: C# XML comments support using <para/> as a line break).
• The only problem with this solution is @joaomoreno thinks it's ugly and likely unnecessary; I have no doubt that there are others who agree with him. The best solution is to have a user preference called something like Intellisense Full Comments: When disabled the current functionality is used (I know that some people prefer a quick one-line summary); When enabled a separate window is displayed that contains the full comments including whitespace (line-breaks at the very least). The full comments displayed in a separate window should look as close to the original comments/documentation as possible, unless the language specific comment syntax explicitly ignores whitespace/line breaks because it has explicit mechanisms for rendering them.
• Parameter documentation should not be displayed in the full comments as it's displayed as parameter hints. If a language doesn't have well-defined parameter hints, then the source comments/documentation should be displayed in the full comments window.
• All non-parameter documentation should be displayed in comments (both full comments and the one-liner version) (meaning don't strip out things like the returns tag the way Visual Studio does).
• The full comments window should ideally be able to render syntax highlighting on the comments (I know this is out of scope, I'm just listing what would be ideal). Example below:

• Ideally, the 'method signature' in the intellisense popup should be rendered using syntax highlighting the same way Visual Studio does it (I know this is out of scope- I'm just listing what would be ideal.). Example: In the picture below the section outlined in red should use syntax highlighting of the corresponding language (JavaScript in this case)
  

---

Details

First, there are two different ways people want to use feature that displays comments about the function that is being selected:

1. People like me: I want to see as much information as possible about the function (basically all of the comments). I have a very large code base and I use comments extensively on every function to document high level information about it, this lets me quickly determine information about the function without having to re-check the source of the function. I use this method in place of external documentation
2. People not like me: Want to see a very brief description of the function to remember what its general purpose is. These people will look at external documentation or the source of the function to get more information. Many libraries (like .NET core libs) don’t’ provide sufficient documentation in the comments that intellisense reads, which forces you to look at external documentation or the source (assuming it's open source- or you have to decompile it).

---

The only way to satisfy both groups of people is to have a user preference for which mode should be used. I already had this discussion for Tern.

Tern has a ‘fullDocs’ option that when enabled returns the full parsed comments and when disabled returns the first sentence of the comments. However, Tern is just the comment parser, which is not exactly what we are discussing here. Instead, we are assuming that the full comments are already returned and we want to determine how they are displayed.
The issue of how the comments are displayed in the popup is more complex than it seems at first glance, because each language has a different structure for comments, some of which include comment sections that are currently not displayed in the comments for the preview of the function (such as parameter information).

---

I see a few questions that need to be answered to implement this properly:

Which parts of the comments should not be displayed in the intellisense comments preview?

I think this is already answered: The parameters should not be displayed (assuming the comment syntax supports parameters) because they will be displayed as parameter hints when inside the function call. However, it's worth noting that Visual Studio also hides the returns section of the comments (if any) from the intellisense comments preview (Monaco includes this section). I strongly prefer showing the returns section in the comments preview (Visual Studio's behavior drives me nuts in this case).

Example function (JavaScript):

/**
 * Performs Magic
 * @param a - anything
 * @returns awesomeness
 * @note this does nothing
 */
function magic(a){
    return a;
}

Monaco:

Visual Studio 2015:

To further complicate things, Visual Studio treats different languages differently (C#):

I think the best solution is to be consistent between languages (don't do what Visual Studio is doing).

---

Should line breaks and whitespace be included in the comments preview?

Currently vscode is not doing this (mainly because its only showing one line). This is absolutely an issue for people who like to read the full comments, especially when you consider that C#'s comment syntax even includes an explicit line break (<para/>) .

Again, I think the best solution is to include whitespace in the comments (line breaks and whitespaces including tabs) - the goal should be to show the comments in the structure that they were written in. However, it's more complex than this because each language-specific comment syntax has different rules. Example:

• C# XML comments have explicit line breaks, therefore whitespace (including line breaks) should be ignored unless using the explicit line break sequence.

The result should be include white-space and line breaks unless the comment syntax has its own explicit mechanisms for this, in which case they must be parsed and turned into the appropriate spacing.

---

How should full comments with line-breaks be displayed?

This is the main point of this thread. So far we have the following ideas:

• Make the selected item in the intellisense popup taller than the others to potentially allow for multiple lines.

I think this would be a decent solution but only if you allow the selected section to also scroll vertically, because an arbitrary height is not going to fit all comments (especially with line breaks).

• Make the selected area auto scroll (horizontally) if it's too big.

I think this is a terrible solution. It prevents line breaks from being displayed (which is non-sense when you have language specific comment syntaxes that support explicit line breaks). Also, the whole point of the comments is to be able to quickly get information you need- waiting on some random auto-scroller to start and scroll at an arbitrary speed would destroy the quick part of getting the information.

• Use a separate window for displaying full comments.

This is the solution most editors use and I think it's the best solution. However, @joaomoreno hates this because its ugly.

[bpasero]

+1 for providing enough space to show comments. I find Atoms solution interesting, its just a box below the IntelliSense window with the text:

[joaomoreno]

That box hits the same issue as us. The question is what does that More... link do.

One plan could be:

1. Like @sevin7676 suggests, embrace the inevitability of needing an extra panel and just implement it.
2. Don't show it by default, but rather a More... link like Atom that would should it. Need a keybinding as well.
3. Provide a configuration option that will just show it always by default, instead of only on demand.

[joaomoreno]

@bgashler1 UI guidance needed here.

[bpasero]

@joaomoreno I would expect that box below intellisense to be as large as to fit the entire contents of the comment. Since that guy is outside of the tree it would not have to compute any height upfront.

[egamma]

actually @stevencl has already come up with a proposal.

[stevencl]

As we get to work on improving the Intellisense design I thought it would be worth going into detail about the two important scenarios that we use to drive our design.

There are a lot of components that contribute to the overall experience that a developer has with Intellisense in VS Code (and other editors for that matter). One tool we use to help us keep track of how those components work together is to design them in the context of the core scenarios in which they will be used.

For intellisense, we have two main scenarios that we use to drive the design. We call these scenarios the 'Red zone' and the 'Green zone' scenarios.

Scenarios

Red zone

In the Red zone scenario, a developer has a task that they need to perform but they don't know what API they need to use to get that task done. For example, they might need to write a line of text to a text file but they don't know what classes or methods they should use to do this. In this scenario, the developer uses Intellisense to discover what classes and methods are available to them. They browse through the suggestion list, looking for methods, classes, namespaces etc that, according to their name, might be relevant to the task. When they find a candidate, they take advantage of the way that Intellisense displays doc comments and other documentation to learn more and to decide whether or not to try the API.

Green zone

In the Green zone scenario, a developer has a task that they need to perform and they know exactly how to do it. In this scenario, the developer uses Intellisense as a shortcut to writing the code. With the suggestion list open they type a couple of characters of text which quickly highlights the class/method/namespace that they want to use. They then press TAB or whatever the autocomplete key is which inserts text in the editor to complete the selected item.

Comparison...

In the Red zone the developer uses Intellisense to help them discover which APIs to use. They take advantage of different UI affordances to help them easily learn how to complete their task.

In the Green zone the developer uses Intellisense to be productive and takes advantage of different UI affordances that allow them to stay focused on the code that they are writing and not be distracted by any other extraneous UI or information.

Next steps

As we work on the design proposal to improve Intellisense in VS Code we will be using both of these scenarios to make sure that we make great design decisions. We want to make sure that any design we come up with allows developers in the red zone and in the green zone to have a great experience.

We will also be gathering feedback from people about our design proposals as we work on them. Let me know if you would like to take part in these feedback sessions.

[Sevin777]

I would add that there is also a Yellow Zone which I commonly use. In this scenario I am looking for methods that I personally wrote (C# in Visual Studio.) However, I've been working on the same project for 4 years straight, so my code base is quite huge. Because of this, I will look for a method with a good idea of which method I want to use, but may not be 100% sure. So I start typing and get down to a few possible methods in the intellisense window, now I need to be able to see my documentation (comments) about the methods in a nice format so I can quickly remember exactly what the method does. The structure of the comments that I'm reading needs to be in the format I specified (line breaks included) and its immensely helpful for the method signature (name, params, returns) to use syntax highlighting to allow me to quickly grab key information about the method. The importance of this yellow zone is that I need to be able to view all of the documentation about the method (not just part of it), and I need that documentation to be in its intended structure (for C# - this includes <para/> line breaks, for JavaScript (jsDoc) I want the original formatting of the comments (try this demo for jsDoc example).

Example of yellow zone usage in Visual Studio:

[stevencl]

Thanks @sevin7676. For simplicity, we would still count that as the red zone scenario. If there is any uncertainty about which API to use to accomplish a task, even just a small amount, we consider that a red zone scenario.

[jcward]

How about an optional CompletionItem.docUri that would show up as a little link on the right. Something like this, but less ugly:

Most of the time you don't need the full doc, but sometimes you do.

[joaomoreno]

Fixed in 163c2c6 by providing extra details view, similar to @jcward's suggestion.

Click the info icon or press Ctrl Space to read more.

Ctrl Space or Escape to go back.

Further improvements to Intellisense tracked in #1134

[byelims]

The type label just hides overflowed text now, how can I see the full text?