Show beginning of docstring rather than description in completion list

[anntzer]

Issue

Currently, the "info" column of the completion list just restates the name of the completion candidate, possibly fully qualified. I would prefer if it showed e.g. the beginning of the docstring (if available), which seems more useful.

See e.g. https://raw.githubusercontent.com/davidhalter/jedi/master/docs/_screenshots/screenshot_complete.png: instead of function: __builtin__.str.ljust, something like Return S left-justified in a Unicode string ... seems more useful. (Actually this is not a great example because str.ljust actually has its signature as first line, but you get the idea.)

Something like

diff --git a/jedi_vim.py b/jedi_vim.py
index 5ddd80a..4764fc0 100644
--- a/jedi_vim.py
+++ b/jedi_vim.py
@@ -191,7 +191,8 @@ def completions():
                 d = dict(word=PythonToVimStr(c.name[:len(base)] + c.complete),
                          abbr=PythonToVimStr(c.name_with_symbols),
                          # stuff directly behind the completion
-                         menu=PythonToVimStr(c.description),
+                         menu=PythonToVimStr(
+                             (c.docstring().splitlines() or [""])[0]),  # docstr
                          info=PythonToVimStr(c.docstring()),  # docstr
                          icase=1,  # case insensitive
                          dup=1  # allow duplicates (maybe later remove this)

is a first step in that direction, but of course a number of improvements are possible, including better handling of objects without docstring (e.g., fallback on the description) and of cases where the first line "looks like" a signature (then skip it and move to the next one).

Steps to reproduce

N/A

Output of “:verbose JediDebugInfo”

N/A

[davidhalter]

I actually like the qualified part. But I can see that there might be possible improvements.. I'm kind of against the docstring, because there will not be enough space for a significant part.

Are there any IDEs that do this differently and better?

[anntzer]

I don't know what any other IDEs may choose to do. Usually, even the first few words of the docstring can be useful IMO. Alternatively, you could display the call signature too -- if you know more or less what you're looking for, that can be enough (well, it depends on how well the API is designed :-)).

[davidhalter]

I decided not to change this. I think VIM's completion interface is simply not flexible enough to experiment here (and also I don't think it's important). So unless there's a very good proposal here I won't change anything.