Proposal: show function head on hover

[giacomocavalieri]

Right, when hovering over a function call, the language server displays its type and documentation.
For example:

pub fn wibble(first_label one: Int, second_label two: Int) -> a { todo }

pub fn main() {
  wibble(1, 2)
}

This is the hover:

What I think it should be

I think the language server could show the function head instead of the type, that is show this:

pub fn wibble(first_label one: Int, second_label two: Int) -> a

Instead of this:

fn(Int, Int) -> a

Why I think this is useful

⚠ This is necessarily reflective of my opinion, there's no objective universal "better", but I'll try and explain why I'd like this change

When writing Gleam it feels great how everything feels right "on hand":

• if a pattern is missing I don't have to jump to a type definition to check what the patterns are: there's an error right under the code telling me what the missing patterns are
• if I need to read the docs for a type, a field, a function, or a constructor I can just hover any of its usages and I will be presented a tooltip with the docs. It would be really simple to just jump to the definition, but it feels better to just include that information in the hover tooltip rather than being forced to jump around in a codebase
• if I hover over a discard .. in a pattern, a tooltip tells me all the fields I'm ignoring. It could be just as simple to jump to the pattern definition, but it feels better when the information is right there and I don't have to jump to some other file (possibly inside a dependency) to see for myself

I think the same goes for function heads: it is easy to jump to a function definition and read for myself the labels and arguments of the function. But it's not as immediate as seeing that in a nice hover tooltip: I have to jump to another file, see what the arguments are, and go back to what I was doing.

What other languages are doing

It's hard to do an apples to apples comparison with other languages as I'm not aware of any other mainstream language that has a distinction between public label and internal argument name.

But I think it's worth it to also see what other big languages do:

• Rust: has no labelled arguments, hovering over a function shows the function head
  
• TypeScript: has no labelled arguments, hovering over a function shows the function head
  
• Java: has no labelled arguments, hovering over a function shows the function head
  
• Python (using pyright annotations): all arguments can be used as labelled, hovering over a function shows the function head
  
• C#: all arguments can be used as labelled, hovering over a function shows the function head
  
• Kotlin: all arguments can be used as labelled, hovering over a function shows the function head
  
• Swift: the closest to Gleam, labels and argument names are separate, hovering shows the function head
  
• Haskell: no labelled arguments, only shows the function type like Gleam
• Cpp (clangd): does this, really hard for me to understand, but it's a different one for sure
  

Every single mainstream language I can think of shows the function head, even languages like Rust, TypeScript, and Java where there's no labelled arguments and the argument name would be an internal detail (like in Gleam) they choose to show those on hover.

What we could do instead

• There's another alternative I can think of that was proposed in the past. That is showing labels in the type displayed on hover fn(Int, some_label: String) -> a. I'm not a fan of this (or any variation on this theme) since that's no longer valid Gleam syntax. A function head, on the other hand, is always syntactically valid Gleam code.
• Or we could just keep showing just the type and docs, I've already explained why I think that's not a particularly great DX compared to how nice Gleam is in other regards

[gungun974]

Just to contribute to "What other languages are doing", dart also show the function head when hover

[hayleigh-dot-dev]

Where the function head includes generics would hovering over the call show the function head with the generics or with the inferred types? If it "fills in" the types is there a potential for this to be confusing?

[giacomocavalieri]

Good point, I've checked Rust and Swift and they always show the function head with the generics, not the inferred type:

I agree that filling in the types with the inferred ones feels like it would be confusing!

[gungun974]

Oh dart however does show you the inferred type bellow the function header when you use generic

[lpil]

Would format the head? What would be the max width?

Would attributes and comments be included?

[giacomocavalieri]

1. I think we could start trying and see how it feels with no formatting, the same we do for types at the moment. As far as I'm aware no one has raised complaints about those not being formatted so far:
   
2. Doc comments are already included today, this shouldn't change:
   

[lpil]

Would it be good to start formatting types perhaps?

[ankddev]

@lpil I think that formatting types would be nice.

[giacomocavalieri]

Yeah totally!

[lpil]

With this change it seems like it may be more challenging to understand the type due to it being more obscured and it not being specialised any more.

I think this may be OK as you can hover specific arguments to see the specialisation, and signature help is still specialised. What do you think?

[idea-list]

I have a UX suggestion but I have no idea if this is too much work or whether this also works in other editors. I know that at least in VSCode-based editors TypeScript extension/LSP has this neat feature that let's users expand types in tooltips. Here's a simple example:

The actions of + and - buttons are titled "Increase/Decrease Hover Verbosity". For TypeScript, if the types are more complex than this example then the user may click + multiple times to make them more and more spelled out. Maybe for Gleam this could be used to show function head by default and specialized types when user clicks + to increase hover verbosity?

[GearsDatapacks]

I'm not aware of an LSP feature that allows us to do this. Likely this is a custom feature of the TS extension

[giacomocavalieri]

I think this may be OK as you can hover specific arguments to see the specialisation, and signature help is still specialised. What do you think?

Yeah I think overall it would improve the experience rather than making it worse, one can always hover the specific arguments to check their types. We could start experimenting with this and see how it feels

[idea-list]

I searched a bit more and yes: this seems VSCode-specific (though possibly not necessarily TS-specific). It looks like there are "proposed" VSCode APIs to support that (e.g. these interfaces), but there are no standardized APIs on LSP side, so the wiring for verbosity levels is somewhat custom.

[gungun974]

With this change it seems like it may be more challenging to understand the type due to it being more obscured and it not being specialised any more.

Yeah now I'm thinking a little more. Gleam is a functional language where we often create and use small function in chain.
However I don't want to have the LSP telling me list.map is pub fn map(list: List(a), with fun: fn(a) -> b) -> List(b) when I'm in a pipe chain.
The current behavior of showing me that's my list.map work with String is more useful here

What this mean is sometime having the raw definition is good but sometime it's just harder to understand how the type parameter work.

(I better understand why dart couldn't decided and does showed both the type and the function head #5463 (reply in thread).)