feature request: doc string in lsp-style floating window

[NoahTheDuke]

i'd like to unify my tooling to prefer a conjure repl connection and fall back on lsp. however, conjure's docstring/hover info prints in the conjure log, not opening a floating window like the lsp.

i'd love to get the same visual style from both tools, or at least get the conjure-based docstrings as data so i can build it myself.

[NoahTheDuke]

i dug into the conjure and nfnl and fennel code, trying to figure out if i could hack this together myself, and I can't seem to figure it out. Fennel's ,doc command calls specials.doc (which returns a string) and then prints it, but to use that you need to provide a bunch of repl-specific information (scopes, environments, etc). fennel.metadata should be able to find it (accessed through conjure.aniseed.fennel), but that requires holding a reference to the function object and i can't figure out how to turn an (: (extract.word) :content) string into a function reference. Maybe through _G? I'm not sure.

[seamusriordan]

For what it's worth I think this is a nice feature request to normalize against lsp behavior.

@NoahTheDuke I'm not sure I follow your discussion on metadata. I was able to hack ... something ... together that roughly does this behavior, at least that works for the fennel client (though I'd expect any real solution should support arbitrary clients). I haven't exhaustively gone through the doc-str implementations, but there may be a path. I'll ramble a bit going forward, but I'm not an authority.

From my perspective there's two issues: One is getting the documentation strings out of a client. The other is wiring it up to the UI.

For the former, the clients I looked at let you pass a callback as the :on-result option to doc-str which is passed the result of the evaluation after completion. In eval.fnl doc-str emits a ConjureDoc event which could be modified to emit the event along with a data payload along the lines of

(vim.api.nvim_exec_autocmds :User {:pattern :ConjureDoc :data data})

There's another :passive? option which suppresses the output to the standard result buffer.

Once you have that you can catch the event setting up a vim.api.nvim_create_autocmd and do whatever logic to open up a floating buffer. I did something hacky with vim.api.nvim_create_buf, but it was sufficient to prove it out.

This may not be the cleanest path and there may be better ways more idiomatic to conjure.

[NoahTheDuke]

thanks for the ideas! i looked over the conjure.eval code and i don't see an easy way to generically call doc-str (and it relies on another local-only function client-exec-fn so can't easily be borrowed), only doc-word which doesn't pass through any opts. if you're willing to share, i'd love to see what you wrote.

[seamusriordan]

The doc-str options gets passed along to the client like so

(local doc-str (client-exec-fn  :doc :doc-str 
                 { :passive? true 
                   :on-result (fn [msg] (event.emit-data :doc msg))
                 }))

and my nonproduction emit-data hack

(fn M.emit-data [name data]
  (let [names (core.map text.upper-first [ name ])]
    (client.schedule
      (fn []
        (while (not (core.empty? names))
          (vim.api.nvim_exec_autocmds :User {:pattern (.. :Conjure (str.join names)) :data data})
          (table.remove names)))))
  nil)

[NoahTheDuke]

oh i see, you're modifying the conjure code directly. i've been trying to do this in my nvim config files. if it's not possible to do locally, i can experiment with modifying conjure to handle this.

[Olical]

Interesting ideas! I'm working on some changes to make this really easy to do from outside for now (so the autocmd will include the docs and the function call for doc lookup calls on-result with the content) but we could consider a built in option too if we can universally agree on how it should work and it doesn't add too much complexity.

[NoahTheDuke]

that's great news. i'll wait to see what you come up with before writing a PR or further suggestions

[Olical]

Okay pushed! Taken from the doc text:

>
              lua vim.api.nvim_create_autocmd("User", {
                pattern = "ConjureDoc",
                callback = function(ev)
                  vim.lsp.util.open_floating_preview(
                    vim.split(ev.data, "\n"), "markdown", { border = "rounded" })
                end,
              })
<
            You can also pass `on-result` directly to `M.doc-word` via
            `extra-opts` for a one-off callback without a global autocmd:
>
              :lua require("conjure.eval")["doc-word"]({ ["on-result"] = print })

So you can either rely on the autocmd to listen for doc output and display that output with a UI of your choice OR replace the mapping and call doc-word yourself which now supports on-result as a param for the clients that support doc lookup (not many of them!).

That should be a passive hook that piggiebacks on what's there as well as another hook you can use to replace what exists with your own that handles the result in whichever way you see fit.

This is still putting the onus on the user to come up with a nice UI though, if there's a universal nice way to do this, maybe it makes sense to implement it and make it the default with an option.

[seamusriordan]

That was fast and I think the event-based abstraction is a nice general way to hook in. I'll check it out.

[NoahTheDuke]

It looks like the neovim hover window (if you call vim.lsp.buf.hover) is created here which calls vim.lsp.util.open_floating_preview here. i don't know how much of that would be useful to outsiders, but either using it directly or building on top of it doesn't seem like it should too hard... (famous last words)

edit: ope, you've used vim.lsp.util.open_floating_preview directly in your example above. boy i wish i knew how to read 😩

[seamusriordan]

After playing with this, it works well when doc-str returns the values as a result (like the fennel client). I am finding that guile and common lisp at least have their results disassociated the eval. I suspect they are returning unprefixed strings rather than a way the result parser understands a result so they just get sent to the buffer as comments.

Some clients may need some tinkering and normalization.

[russtoku]

I am finding that guile and common lisp at least have their results disassociated the eval.

I too have noticed that clients vary in the way they handle things. I'm still trying to fully grasp how things are done for the Clojure and Fennel clients in an effort to get a better sense for a "standard" way of doing things.

For example, a couple of days ago I noticed that the Clojure and Common Lisp clients use conjure.net via conjure.remote.nrepl and conjure.remote.swank to open a TCP connection. The Guile client uses conjure.remote.socket because it originally just handled communication via UNIX-domain socket or pipe file. I added TCP connection to it give Guile clients more flexibility. Now, I'm thinking that it would have been better to split things into separate remotes and have conjure.client.guile.socket and conjure.client.guile.tcp (or some other name).

Apologies if this seems like a rant but these kinds of issue highlight the need for refactoring and redesign as expressed in #500. Ideas and suggestions from others could be helpful.

[russtoku]

I forgot to mention that not all clients implement doc-str.