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

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

annotation example

---@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

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

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

top-level version declaration

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

using config actions

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

-- lib.lua

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

-- main.lua

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

by library author, from annotation

-- lib.lua

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

-- main.lua

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

by library user

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

Trước tiên, hãy đọc các ví dụ về annotation, sau đó so sánh .luarc.json được đề xuất, meta/3rd/$lib/config.lua và các nguồn phiên bản theo từng module. Issue không nêu tên các tệp triển khai hoặc test và mô tả một số giai đoạn có thể có, vì vậy trước hết cần thống nhất phạm vi để hiển thị @since, @deprecated và @removed trong tài liệu thư viện. Điều kiện hoàn thành phải bao gồm cú pháp annotation được định nghĩa và cách hoạt động của nguồn phiên bản.