Documentation using Help buffer

[krisbalintona]

Hi,

When using corfu, showing documentation (at least of elisp symbols) via e.g. corfu-info-documentation will use the existing Help buffer. The documentation is shown fine, but when I'm using that help buffer, it's a bit troublesome because it clutters the help buffer history.

Is this intended? And if so, are there any workarounds for corfu not to use the Help buffer.

[minad]

Is this intended? And if so, are there any workarounds for corfu not to use the Help buffer.

Buffer creation is a matter of the backend. I don't think we can guard the existing buffers from being modified by the backend. Ideally the backends would return new and unique buffers.

[krisbalintona]

That makes sense... I took a quick look at corfu's code and couldn't quite figure out where the help.el would be invoked. The most I could make sense of it is that corfu-info-documentation and corfu-popupinfo--get-documentation get the :company-doc-buffer property of completion-in-region--data. Beyond that, I can't tell where a user could intervene in the process such that the help buffer isn't used.

Any suggestions?

[bR3iN]

That makes sense... I took a quick look at corfu's code and couldn't quite figure out where the help.el would be invoked. The most I could make sense of it is that corfu-info-documentation and corfu-popupinfo--get-documentation get the :company-doc-buffer property of completion-in-region--data. Beyond that, I can't tell where a user could intervene in the process such that the help buffer isn't used.

Any suggestions?

The buffer to use for displaying the documentation (at least for elisp symbols) seems to be elisp--company-doc-buffer, which internally calls help-buffer. As a workaround, it works to temporarily overwrite help-buffer to create to use a different buffer than *Help*:

(require 'cl-lib)

(advice-add
 'elisp--company-doc-buffer
 :around (lambda (orig &rest args)
           (cl-letf (((symbol-function 'help-buffer)
                      (lambda ()
                        (get-buffer-create "*Help-Preview*"))))
             (apply orig args))))

Could maybe be fleshed out a bit by automatically deleting the newly created buffer at the end of the completion or by advising a function higher in the chain, but worked fine for me so far to not change a currently displayed *Help* buffer when cycling through completion options with corfu-popupinfo-mode (which drove me a bit insane).

[jdtsmith]

Instead of using advice and cl-letf, you could "fix" the offending CAPF using cape-wrap-properties to wrap the CAPF's :company-doc-buffer property (likely elisp--company-doc-buffer here). In your wrapper function, you could let-bind help-xref-following=t, create and switch to a buffer with your desired name, put it into help-mode, then call the original :company-doc-buffer function.

[krisbalintona]

Instead of using advice and cl-letf, you could "fix" the offending CAPF using cape-wrap-properties to wrap the CAPF's :company-doc-buffer property (likely elisp--company-doc-buffer here). In your wrapper function, you could let-bind help-xref-following=t, create and switch to a buffer with your desired name, put it into help-mode, then call the original :company-doc-buffer function.

Thank you @jdtsmith. I've arrived at the solution below:

(defun krisb-corfu-popupinfo--doc-buffer (str)
  "Wrapper around `elisp--company-doc-buffer'.
This function is a replacement for `elisp--company-doc-buffer', which
normally returns the main Help buffer (returned by `help-buffer').
Instead, this function returns a separate buffer to use as the Help
buffer.

Accepts the same argument as `elisp--company-doc-buffer' (STR).

Meant to be used with `cape-capf-properties' on the `cape-elisp-symbol'
completion at point function.  This ameliorates the sometimes
undesirable issue described in
https://github.com/minad/corfu/discussions/504#discussioncomment-12592545.

This solution was taken from the suggestion of
https://github.com/minad/corfu/discussions/504#discussioncomment-12593463."
  (let* ((help-xref-following t)
         (new-help-buf-name
          "*corfu-popupinfo documentation*")
         (new-help-buf (get-buffer-create new-help-buf-name)))
    (with-current-buffer new-help-buf
      (help-mode)
      (elisp--company-doc-buffer str))))

;; "C-c / s" is my keybind for `cape-elisp-symbol'
(bind-key "C-c / s" (cape-wrap-properties 'cape-elisp-symbol :company-doc-buffer #'krisb-corfu-popupinfo--doc-buffer))

I wouldn't have been able to figure this out on my own because I don't have the requisite understanding of help.el and corfu. Thanks!