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?

[giacomocavalieri]

Showing the labels could solve the problem there perhaps

Mhm though a previous PR I made doing that was closed because we agreed showing something that is not valid Gleam syntax (the type annotation with the labels too) would be more confusing

[lpil]

iirc I closed it before because we show the type at the top of hover and it wasn't a valid type, but now we're discussing replacing the type with some new information. I'm not sure what would be best, and how we modify non-module-function hover information.

[giacomocavalieri]

As for non-module-functions the inferred type seems fine, I haven't seen any complaints about that. I think it would be more useful to show the function head on hover

[gungun974]

That's only my opinion but I have some apprehension there is only two answer. Either do nothing or do both like dart.
I don't see good middle ground

[gavinmorrow]

Since the specific types can be found by hovering over the arguments, imo it should definitely show at least the generic types. I wouldn't be opposed to having both like dart.