LuaLS / LuaLS/lua-language-server

Function Overloading Overhaul (`@function` annotation)

Offen
#1,456 22 Kommentare 24 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

enhancement
Vorherrschende Sprache
Lua
Sterne
4.4k
Forks
442
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

# The Problem
I think function overloading needs some changes in order for it to really function in the way that most people would find useful. This is especially problematic with event systems, as I and [others](https://github.com/sumneko/lua-language-server/discussions/1452) have encountered.

# Example
Currently, let's say I have the following function that I want to provide an overload for:
```lua
function Shape:listen(event, callback) end
```

## Using `@overload`
The first logical option is to use [`@overload`](https://github.com/sumneko/lua-language-server/wiki/Annotations#overload):
```lua
---@class Shape
local Shape = {}

---Subscribe to an event on this shape
---@param event "Destroy"
---@param callback fun(self: Shape)
---@overload fun(event: "Repair", callback: fun(self: Shape, amount: number))
function Shape:listen(event, callback) end
```
But there is a problem, when using methods (`:`), the first parameter only gets completions for the first `@param` and ignores the `@overload` entirely.
![image](https://user-images.githubusercontent.com/61925890/183683092-958d747c-0979-4834-b172-3559a658994a.png)
Ok, so for testing, let's replace the method (`:`) with a static function (`.`):
```lua
---@class Shape
local Shape = {}

---Subscribe to an event on this shape
---@param event "Destroy"
---@param callback fun(self: Shape)
---@overload fun(event: "Repair", callback: fun(self: Shape, amount: number))
function Shape.listen(event, callback) end
```
This still isn't great, we are still offered both callbacks even though the info we have entered only matches the `@overload`. At least the first parameter was completed this time.
![image](https://user-images.githubusercontent.com/61925890/183684285-b6b125ba-c6b1-487a-8dec-1a4c5b5f2c2f.png)

## Multiple Definitions
So then maybe we try defining multiple functions where each `event` param has the type set to the event name we are looking for:
```lua
---@class Shape
local Shape = {}

---Subscribe to an event on this shape
---@param event "Destroy"
---@param callback fun(self: Shape)
function Shape:listen(event, callback) end

---Subscribe to an event on this shape
---@param event "Repair"
---@param callback fun(self: Shape, amount: number)
function Shape:listen(event, callback) end
```
Now, even as methods (`:`) we are receiving correct completions for the first parameter... nice! However, we are still receiving two completions for the callback - there is no narrowing happening. The completion also shows the `event` as `"Destroy"`, which is incorrect for our second definition as we have only allowed `"Repair"`.
![image](https://user-images.githubusercontent.com/61925890/183685902-164bb942-f11c-4dd6-bac5-dacb45af0891.png)
At least when defining the function twice, we are able to write a separate description for each of them as well as their `@param`s and `@return`s. However, we receive a warning saying that we have a duplicate field.

# Proposed Solution
See @flrgh['s idea](https://github.com/LuaLS/lua-language-server/issues/1456#issuecomment-1210963693) to add a `@function` annotation to add more in-depth support for defining functions overall.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit den @overload- und Mehrfachdefinitionsbeispielen des Issues und lies anschließend den verlinkten Vorschlag von @flrgh für die @function-Annotation. Die Arbeit ist abgeschlossen, wenn Funktionsdefinitionen die vorgeschlagene Annotation mit korrekten ereignis- und callback-spezifischen Vervollständigungen unterstützen, ohne die hier beschriebene Warnung vor einer doppelten Definition.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
lua
Bereich
devtools
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.