LuaLS / LuaLS/lua-language-server
Function Overloading Overhaul (`@function` annotation)
Dieses Issue hat noch niemand übernommen.
- 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.

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.

## 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"`.

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
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Ö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