company-show-doc-buffer: automatically grow and shrink the window as needed

[vemv]

Context

I'm (re)implementing CIDER's Company completions for Java (if you are very curious: clojure-emacs/cider#3472).

Part of that is integrating a function for :company-doc-buffer, like cider-create-doc-buffer.

Problem statement

The buffers that we will render are predictably and guaranteedly short. A buffer for :company-doc-buffer, as created with cider-create-doc-buffer will not have more than ~20 lines (as set with our new defcustom cider-docstring-max-lines 20).

So, for us, it's always safe and usable to render the buffer produced company-doc-buffer in its entirety. i.e. the window should always be large enough to not produce scrolling.

By not producing scrolling, users can use the docstrings we produce at a glance, without further interactions needed. From what I could try, scrolling on the produced buffer is a quite glitchy (because we are in the middle of a completion).

Request

Create an option, similar to :company-doc-buffer, that expresses that the produced buffer should be rendered in a window that will automatically:

• shrink if its window is larger than necessary
• grow if its window is smaller than necessary

Because this option would be opt-in, it would not result in a generalized UX change.

Sample code

In case it helps.

This is what I'd like to specify:

            :company-kind #'cider-company-symbol-kind
            :company-doc-buffer #'cider-create-shorter-doc-buffer
            :company-location #'cider-company-location
            :company-docsig #'cider-company-docsig
+           :company-docsig-auto-shrink-grow t

And this is what I'd suggest that Company does when encountering that option:

(defun my/count-buffer-lines ()
  "Count the number of lines in the current buffer."
  (save-excursion
    (goto-char (point-min))
    (count-lines (point-min) (point-max))))

(when company-doc-buffer-auto-shink-grow ;; the hypothetical property I'm requesting
  (let ((buffer ... ;; the buffer created by company-show-doc-buffer
                ))
    (with-current-buffer buffer
      (with-selected-window (get-buffer-window (current-buffer))
        (let* ((desired-height (my/count-buffer-lines))
               (actual-height (window-body-height))
               (delta (- desired-height actual-height)))
          ;; enlarges/shrinks the window as needed:
          (enlarge-window delta))))))

WDYT?

Thanks - V

[dgutov]

From what I could try, scrolling on the produced buffer is a quite glitchy (because we are in the middle of a completion).

FWIW, it can be scrolled with either C-M-v/C-M-S-v, or with the mouse. We explicitly set it as the "other window".

[vemv]

For some reason, scrolling doesn't work so well when Company has rendered multi-line strings to the echo area.

OTOH, today I've been discovering new patterns for Company usage. I've used Company for roughly 5 years, heavily relying on the echo area.

With company-auto-update-doc I no longer need/want the echo area for showing docstrings.

Refraining from using the echo area has other benefits, like no more echo-area blinking as one switches to the next candidate.

All of which is to say, when scrolling actually works, it becomes a viable, and minimalistic/agnostic solution. And it works for all cases I now want to use/foster.

Please consider my feature request retracted!

[dgutov]

For some reason, scrolling doesn't work so well when Company has rendered multi-line strings to the echo area.

Do you mean the echo from the meta backend? It was never supposed to be multiline, I think.

Please consider my feature request retracted!

Cool. Let me know if you change your mind, I'm happy to try to enable different workflows. 🙂

[vemv]

Do you mean the echo from the meta backend? It was never supposed to be multiline, I think.

It worked well enough tbh, but I'm ready to leave that hack behind 😄

[dgutov]

Regarding the meat of the proposal: maybe we should make this a user option? Rather than a property of a backend.

Some people will like it, some won't. And there's bound to be other backends/completion sources that have short enough docs.

Further, while I don't really mind, automatic shrinking might not always look great: e.g. if the other window in the same vertical group already contains a short buffer, especially if that window was also previously shrunk for that buffer's display. Growing OTOH should generally make sense, to help the user read the whole text.