Show function argument documentation in hovers

[Anton-Latukha]

I'd loved to see those function "signature comments" displayed. HLS already helps to write them. I found them often being a true way of documenting what function does, as people often in function docs just white what functions accepts & does with args - people write that style way quite intuitively & that fits greatly to be a signature comments. To see those sometimes would be an immense simplification to read code.

Several years ago - I remember the dialog that Haddock-like signature comments were not yet in the LSP protocol specification.

What is the current status there (and here 8) )?

As I arrived though reading lsp-haskell -> lsp-ui -> lsp-mode -> searching though HLS & looking at Microsoft LSP specs and seeing there as good as 🦇 🕶️ 😎 🌃 〰️ 🌙 〰️ & in that way I arrived here. & decided you should know something about what are the current affairs there 8)

[michaelpj]

I think this is a HLS issue. What you see there is the hover documentation for an element, this is just markup, and so it's entirely up to the server what it puts in there. I don't know how HLS gets the information that goes in there.

[Anton-Latukha]

Hey, great! Thanks for the direction & transfer. & Thanks for showing the place to look at in the spec.

[Anton-Latukha]

Actually I happen to touch-related code yesterday. I already have some minor changes in the local branch.
It is foundHover -> hover -> Spans/AtPoint.hs hoverInfo - somewhere around there, trying looking it up ... _<loading> ...

[Anton-Latukha]

Probably GHC stores annotation info in https://hackage.haskell.org/package/ghc-9.2.1/docs/src/GHC.Iface.Ext.Types.html#NodeInfo

& nodeInfo retrieves it. So it is a question of where & how to show nodeAnnotations besides nodeType.

[Anton-Latukha]

Seems like I almost pieced everything together. Only searching where the signature comments are hidden. Since https://hackage.haskell.org/package/ghc-9.2.1/docs/src/GHC.Iface.Ext.Types.html does not have anything on Doc(umentaion) or Com(ment).

But at least something currently:

I wonder, does GHC exposes signature comments or not, we well could lived on Haddock parsing signature comments all this time.

Maybe I just need to look into lookupNameEnv.

[michaelpj]

I think GHC may not store those, we may need Haddock here. In fact, I'm not sure why we aren't getting this information from Haddock in the first place?

[pepeiborra]

HLS gets docs from interface files. Docs on arguments are also available, just hoogle mi_arg_docs. This would be a very welcome contribution to HLS.

[pepeiborra]

In fact HLS already does the work to retrieve argument docs in getDocsBatch, but then throws them away immediately (unwrap):

haskell-language-server/ghcide/src/Development/IDE/Spans/Documentation.hs

Lines 70 to 76 in ec53fcb

	res <- catchSrcErrors (hsc_dflags env) "docs" $ getDocsBatch env mod names
	case res of
	Left _ -> return []
	Right res -> zipWithM unwrap res names
	where
	unwrap (Right (Just docs, _)) n = SpanDocString docs <$> getUris n
	unwrap _ n = mkSpanDocText n

[Anton-Latukha]

Thank you - it was twice removed for where I managed to search in, I never arrived into https://hackage.haskell.org/package/ghc-9.2.1/docs/GHC.html#v:mi_arg_docs.

getting this information from Haddock in the first place?

• it may be needed, in the future or for additional features. But as a newcomer - I would not overset goals & would currently do the basic implementation.

GHC implementation should be both more elegant, everything is/can be retrieved from one place, in the same format & should be in the same scope, it would not need syncing of positions & their types conversions & regarding format - there is already internal conversion of Haddock syntax to markdown happening inside HLS that seems to be used widely.

I wonder - would I need to do GHC API version support: https://github.com/haskell/haskell-language-server/pull/2338/files (I wish to do minimal MVP first).

[konn]

FYI: here is the similar feature request got staled a month ago: #2258.
I haven't tried even further there, so I think we can close #2258 in favour of this issue.

[Anton-Latukha]

GHC has upstream progress on this subsystem in the pipeline: https://gitlab.haskell.org/ghc/ghc/-/merge_requests/6224

[pepeiborra]

I don't think that GHC support is required here, see my earlier comment:

#2348 (comment)

[Anton-Latukha]

I don't think that GHC support is required here
Yes, GHC already provides the needed argument information.

---

I was distracted for some time, because, when working on the arg doc code, noticed CI was a bit 🐌, so shaved a 🐃 CI caching loop a bit to make CI bounce compat-checks on me faster 🤣.

---

Just collecting related arg doc pipeline info here, since that massive PR on arg docs in GHC is nearing merge - I need to know about it. & also to establish communication/collaboration between GHC process & HLS process in the theme, which already produced useful feedback: #2371 (comment)