Automatically expand full docstring when autocompleting

[fredrikaverpil]

As originally posted as a feature request in the pythonVSCode project:

Would it be possible to automatically expand the docstring without requiring clicking the "info" symbol button?

Current behavior requires you to click the "info" symbol button to view the full docstring:

For comparison, here's how Atom deals with this (always expands the full docstring):

Also, it would be useful to be able to copy paste e.g. a function's arguments from the documentation shown.

[ramya-rao-a]

Tried my hand at this and below are a few options.

Docs shown below the suggestion list

Docs shown below the suggestion list + reduced suggestion count so that the item in focus is nearer to the docs. Less jumping of user's focus between item in focus and the docs?

Docs shown side to side

In all cases the height of the docs section is fixed and the docs is scrollable.
Some smart logic can be added to make the height of the docs dynamic.
But different font-sizes and fonts would render text with different width. So that can get tricky.

I propose to add a setting editor.suggestAutoExpand with true/false: false by default
Or with off, below, side. off by default
Get user feedback and then take it from there.

Thoughts anyone?

cc @Microsoft/vscode

[mrmlnc]

@ramya-rao-a, I'm outside @VScode scope, but I'm in. I think this is a very useful feature.

[Tyriar]

@ramya-rao-a the ones on the bottom need either a top border or a different background color imo.

[ramya-rao-a]

@mrmlnc So sorry, didn't mean to exclude anybody, updated my text :)

[roblourens]

I really like the last option, showing them to the right (but I agree that it should be configurable)

[Tyriar]

I'm not sure making this configurable and supporting multiple configs would be worth it. I certainly wouldn't assume that it would be configurable and seek out a setting to change it.

[chrisdias]

VS has been finely tuned for a number of years and pops a window to the right, so #3 is consistent with this behavior. VS pops the flyout after a slight delay it appears, presumably to let you quickly scroll through the IntelliSense list and not be distracted by the flyouts. The flyout window is sized for the content, it does not take up the full height of the IntelliSense list. This is goodness because it obscures less of the screen/underlying code, so I'm in favor of dynamically sizing the doc area.

What happens when the editor is too narrow or if the completion is near the end of a long line?

[ramya-rao-a]

@chrisdias
When completion is near the end of a long line, the suggestion list as well as the docs show up on the left side of the cursor just like it does today.

With narrower editors, the whole section resizes to fit itself.

[joaomoreno]

I would stay away from any configuration and just provide a single good solution.

Overall I really like option 2, if we further decrease the number of options (3-5) and make the height of the documentation variable, taking up as much space as it needs up to a certain point, when it becomes scrollable.

[ramya-rao-a]

Here are some updates:

The side by side option with the docs now having dynamic height instead of fixed height

The below option with lesser items, border between items and docs and dynamic height instead of fixed height

[Tyriar]

@ramya-rao-a it would be good to trim any new lines/whitespace at the bottom of the detail message

[ramya-rao-a]

Those are not newlines/whitespaces. That is just me trying to guess how may lines the docs may need.
Which is different for different font-sizes.

Right now I have an approximation logic that works for most cases, and for a few you see a max 2 empty lines in the end.

Logic I am using (pretty hacky) is number of chars that fit in a line = 720/fontsize

Anybody has any other ideas here, please do share.

Now in certain languages (example chinese), chars are wider. So this will not be accurate. Still working on that part

[ramya-rao-a]

Worked offline with @Tyriar (thanks @Tyriar!) and we now have the dynamic height being set without us needing to guess the number of lines the docs would take. Yay!

[fredrikaverpil]

Wow, this looks fantastic @ramya-rao-a !

[octref]

Don't know if this belongs to here, but hope the suggest item's

• documentation can be rendered as Markdown
• function signature can be syntax-highlighted

[ramya-rao-a]

@octref can you log a separate issue for that?

[ramya-rao-a]

Update:

The Insiders Build of 5/9 will have the below features.

• Docs show up on the right, widget flows across editor groups if cannot fit in active editor group
• The list and docs get swapped such that the list is always closer to the cursor position
• Docs go below the list when there is not enough space to show the two side by side

[svipas]

@ramya-rao-a Very good job. Thank you a lot. This feature is AMAZING!

[ramya-rao-a]

Update:

In addition to #18582 (comment), the Insiders Build of 5/18 will have the below features

• Ctrl+Space to expand/collapse the docs. This user choice is persisted to give the "expand docs all the time feature". This way we don't need a setting to control the docs expansion
• Ctrl+Alt+Space to move focus to the docs and back to the list. This controls which part (list vs docs) is used by the below commands:
  • selectNextPageSuggestion (Page down)
  • selectPrevPageSuggestion (Page Up)
  • selectFirstSuggestion (Scroll to top)
  • selectLastSuggestion (Scroll to bottom)
• Screen reader support:
  When the docs are not expanded, moving up and down the list, the screen reader will read the label of the completion item in focus.
  When the docs are expanded, moving up and down the list, the screen reader will read the label of the completion item and then the docs
• Close icon for the button that closes the expanded docs instead of the previous "Go back" icon

[svipas]

@ramya-rao-a Very good, but I think the setting will be good or make it by default to expanded/collapsed, because it's way better than before. I think if people forgot to use Ctrl+Space on new VS Code installation or if they want to send same settings to friend/college they need to use Ctrl+Space to expand/collapse the docs. With setting or making it by default it will be way easier to send settings to have the same configuration on VS Code or to use it every time even if you forgot to press Ctrl+Space. This feature must to be turned on by default or have setting instead of Ctrl+Space configuration. A lot of people who want this feature and don't manually read new VS Code release note can't find it in settings and maybe they will create issues or just don't use it, because they think this don't exists. I know it's more job to make settings and so on, but believe me this feature change the VS Code to the next level. My main criterion why I chose VS Code is the best autocomplete ever, but the problem was with the docs.

[ramya-rao-a]

Thanks for the feedback @svipben

cc @seanmcbreen who is currently looking at default behavior/default settings of the product etc.

cc @Microsoft/vscode and everyone else on this thread for thoughts on what the default should be. Ctrl+Space can always be used toggle between expand/collapse.

[chrmarti]

For discoverability I would show it expanded by default. It is much easier to imagine what the close button does than what the info button might do. This is especially true for new users.

Also: I guess many users will keep the default and not showing the doc would just keep that feature from them.

[fredrikaverpil]

I also wish to somehow make it expanded by default. A setting in settings.json is fine with me.
I personally prefer the settings appearing on the side. ❤️

I like the docs on the side as then this section won't jump around and will always start just under the line where I'm typing.

[svipas]

@chrmarti @fredrikaverpil I love you guys! 😄

[ramya-rao-a]

@fredrikaverpil

I like the docs on the side as then this section won't jump around and will always start just under the line where I'm typing.

Can you elaborate on which section jumps around and when in the latest insiders?

[fredrikaverpil]

Can you elaborate on which section jumps around and when in the latest insiders?

Perhaps "jumping around" was not the best way to describe what I meant. :)

What I meant was that when you hit ctrl + space, the list of available objects varies and so does the height of this list. If you opt to have the docs at the bottom, your eyes won't immediately know exactly where the docs will show up; thus the docs text "jumps around"...

Instead, if the docs appear on the side, your eyes will know exactly where to look for it, as it always appears just below the line where you are typing.

I merely wanted to point out why I preferred the docs text on the side, and this was why.
Does this make sense to you and does this answer your question?

[fredrikaverpil]

@ramya-rao-a perhaps I found a bug...

Please see here (Quicktime): https://drive.google.com/open?id=0B0b1IUnYqENgdk9nU0R1UjlmZ0U
I first hit ctrl + space to bring up the list of objects. Then I hit ctrl + alt + space to show the docs at the bottom. See how the docs text doesn't update while I move up and down the list of objects?

I noticed this when I was going to answer your previous question. This is on macOS.

EDIT: Added a Quicktime showing it works great with the docs expanding to the side: https://drive.google.com/open?id=0B0b1IUnYqENgbW1tVy1PRV8zeFk ❤️

[ramya-rao-a]

Good catch @fredrikaverpil
Ctrl+Alt+Space was meant to move focus between list and docs but only if the docs was already expanded.

Fixed with c671df0

The fix will be out in Monday's insiders

[AndyBay]

Right now when expanding docs for local variables with no documentation, the widget window shrinks when it previously did nothing. Is this supposed to happen?

I much preferred how it was a couple updates ago with the expanded docs to the side. Will there be an option for the placement or is it now set to be below?

[ramya-rao-a]

@AndyBay No thats not suppose to happen.

The docs are suppose to expand below only if VS Code window is too small to accommodate the side by side view.

The list section shrinks only when docs are to expand on the side. When docs end up below, they shouldn't shrink.

Are you on the latest insiders?

[AndyBay]

@ramya-rao-a I currently use "window.zoomLevel": -1 which seems to force placement below. If I change the setting to 0 I get correct placement to the right side.

I currently work on a laptop with low resolution so I need to zoom out a bit.

I am on the latest insiders yes.

[Tyriar]

@AndyBay that's captured in #26886

[Tekbr]

-- Sorry for the English, I used Google Translator --

@ramya-rao-a Some things I do not understand. So sorry for my silly question, but how do you make the suggestions look like this?

or

[ramya-rao-a]

@Tekbr that happens only when the VS Code window is too small to hold the docs on the side of the list.

[Tekbr]

-- Sorry for the English, I used Google Translator --
@ramya-rao-a Is there an issue with this request to be on the bottom? That is, make it configurable?

[ramya-rao-a]

@Tekbr no, but you can open a new issue for that. If it gets considerable up votes, we will consider adding a setting