LuaLS / LuaLS/lua-language-server

feature: @since/@deprecated/@removed annotations for 3rd party libraries

Ouverte
#1,132 0 commentaires 4 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

enhancement feat/LuaCats Annotations
Langage dominant
Lua
Étoiles
4.4k
Forks
442
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

I'd love it if we were able to use version markers for 3rd party libraries. OpenResty annotations would benefit from this.

## annotation example

```lua
---@meta
local lib = {}

--- This function was added in lib 1.1.3
---
---@param a string
---@param b string
---@since 1.1.3
function lib.new(a, b) end

--- This function was added in lib 1.1.0 but has been deprecated since 2.0
---
---@param a string
---@param b string
---@since 1.1.0
---@deprecated 2.0
function lib.deprecated(a, b) end

--- This function was added in lib 1.1.0 but has been deprecated since 2.0 and removed in 3.0
---
---@param a string
---@param b string
---@since 1.1.0
---@deprecated 2.0
---@removed 3.0
function lib.removed(a, b) end

--- This function was added in lib 1.0
---
---@param a string
---@param b string
---@since 1.0
function lib.updated(a, b) end

--- ...and the signature was changed in lib 2.0 to add a 3rd param
---
---@param a string
---@param b string
---@param c string
---@since 2.0
function lib.updated(a, b, c) end

return lib
```

Initially, the language server could just add these things to the function's documentation.

Once this feature is in place, the next stage would be to make the language server aware of which version of $library is being used. Then, the language server could use this contextual info:

* provide type hints, docs, etc that are specific for the version being used (see `lib.updated` from my example)
* provide diagnostics
* "warning: `lib.deprecated` has been deprecated in version 2.0 (your version: 2.1)"
* "error: `lib.removed` was removed in version 3.0 (your version: 4.7)"

## discovering the library version

Here are some ideas I have:

### explicitly-configured by the user

`.luarc.json`

```json
{
"workspace": {
"library.version": {
"OpenResty": "1.2.3",
},
}
}
```

### discoverable from meta/3rd/$lib/config.lua

#### top-level `version` declaration

```lua
version = function(workspace_dir)
-- do something to determine the version
return require("my_library").meta.version
end
```

#### using config actions

```lua
configs = {
{
key = 'Lua.workspace.library.version.OpenResty',
action = 'set',
value = (function()
return require("my_library").meta.version
end)(),
},
}
```

### per-module annotation

#### by library author, from table key

```lua
-- lib.lua

---@version-from-field _VERSION
local lib = {
_VERSION = "1.2.3",
}
return lib
````

```lua
-- main.lua

local lib = require "lib" -- version is 1.2.3
```

#### by library author, from annotation

```lua
-- lib.lua

---@version 1.2.3
local lib = {}
return lib
```

```lua
-- main.lua

local lib = require "lib" -- version is 1.2.3
```

#### by library user

```lua
---@version 1.2.3
local lib = require "lib"
```

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Read the annotation examples first, then compare the proposed .luarc.json, meta/3rd/$lib/config.lua, and per-module version sources. The issue does not name implementation files or tests and describes several possible stages, so first agree on the scope for exposing @since, @deprecated, and @removed in library documentation. Done should include defined annotation syntax and version-source behavior.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
lua
Domaine
tooling
Type d'issue
Fonctionnalité
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
À clarifier
Accessibilité débutants
25/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.