Debugging lack of documentation via `K` in clojurescript (using shadow-cljs)

[kovasap]

Sometimes when using Conjure the documentation feature (using K over a symbol to retrieve its documentation) doesn't give me any information besides just the name of the symbol. All other Conjure features seem to work (evaluating code, etc.). Any ideas on how I could get more info to help with debugging this?

[rlch]

@Olical +1, I'm using fennel and documentation seems to be the only feature not working. Always gives me:

It's also worth noting that, at-least for me, the built-in keywords (local, fn, ...) are the only symbols that seem to receive documentation.

Thanks for the great plugin!

Edit: Documentation works when my client is conjure-client-fennel-stdio.

[Olical]

I haven't had time to look into this deeply yet but I can say from anecdotal experience that ClojureScript doc lookup has always been patchy for me too. As for Fennel, I recently merged a PR that swapped from the old (doc ...) form to ,doc ..., I wonder if that has something to do with it.

Fennel code when compiled without a specific flag doesn't actually have any doc metadata, so this is more a Fennel thing than anything. If I enable that metadata in Aniseed's compiler then the Lua on disk will get a lot bigger and slower to load. So the docs should attach when you dynamically eval the code with Conjure but it won't be there if it's been passively compiled by Aniseed and loaded from disk... I think.

There may be stuff I can do to improve the Fennel one. The ClojureScript issue has me thinking, you mentioned K but I moved the default mapping away from that a while ago since it conflicted with all of the LSP clients. It should be <prefix>gk now, does that work for you instead?

If you're hitting the right mapping, it might be an issue like the Fennel one: The function just doesn't have any doc metadata on it. So we have to verify: Is the REPL not returning anything (not much I can do from my end I don't think), is Conjure sending the wrong code or is it ignoring a good response.

You can see the raw messages flowing in and out of Conjure by setting :let g:conjure#debug = v:true, that'll be noisy but it'll show you everything Conjure says or hears. I hope this helps a little but I can look into this deeper soon.

[Olical]

Hmm I can't reproduce this through shadow-cljs

; --------------------------------------------------------------------------------
; doc (word): xyz
; -------------------------
; dev.foo/xyz
; ([])
;   Hello world

Or Fennel for core functions

; --------------------------------------------------------------------------------
; doc (word): +
"(+ a b ...)
  Arithmetic operator; works the same as Lua but accepts more arguments."

So when it comes to CLJS I think it's probably more down to the REPL or the mapping you're using? Since Conjure doesn't use K as the default doc lookup mapping anymore (because it conflicts with other plugins and systems like LSP as I mentioned in the previous comment).

Fennel is another story, since only core functions seem to work maybe I need to tweak the compiler flags, I'll look into that. You will however always run into issues where the docs aren't loaded if you load the code from Lua (i.e. from a pre-compiled file with Aniseed). You have to dynamically eval the Fennel source code since I elide compiler meta data when Aniseed compiles Fennel -> Lua for efficiency reasons.

I could maybe add it in or with an option but you add more code / load time for the odd doc lookup when you can get that data by evaluating the Fennel source once Neovim's open anyway. It's a tradeoff and I don't think there's a right answer for everyone there.

So I'll look into the Fennel metadata a bit but the CLJS side looks fine for me, I can't reproduce the issue. Maybe some nREPL setups lack the doc operation? shadow-cljs should be fine though, so it might just be the mapping you're using.

It could be similar to the Fennel issue too: When shadow-cljs first loads your code it might drop metadata, when you dynamically eval it with Conjure that metadata is applied... in which case there's nothing I can do there really other than recommend the same as I do for Fennel: Eval the file you're working with and the metadata should be attached, otherwise we're at the mercy of the REPL and how it chooses to load the code.

[Olical]

Spent quite a while trying to work out the Fennel doc issue but I'll have to come back to it. I'm passing all of the correct options so it should work fine but it's not. I wonder if it's some sort of bug inside Fennel but I kind of doubt it, probably to do with the way I keep the Fennel modules under an aniseed prefix and it throws off the metadata lookup somehow.