Feature Request: Deprecate fields and parameters

[Rouneq]

Could really use a clean way to mark specific field and parameters as deprecated. Currently I'm adding @**[DEPRECATED]** to the start of the comments for the field/parameter, but this doesn't change the name with a strike-through (as happens with functions).

[sumneko]

You can use ---@deprecated for field.
But there is no way for parameter.

[johannesrld]

You can use ---@deprecated for field.

how 🤔 im trying

---@class foo
---@deprecated
---@field example string
foo = {}

but it does not work

[bavalpey]

Would like to see this as well.

[TIMONz1535]

I see that it partially works because you can use on ---@type, but it has an issues - the behavior completely changes for the local defined classes

Lua code

---@deprecated -- does nothing
---@class foo
---@field example string
local foo = {}

---@deprecated
---@type string
foo.example2 = nil

print(foo)
print(foo.example) -- cant mark as deprecated
print(foo.example2)


---@class foo2
---@deprecated -- breaks the local class declaration, and does nothing
---@field example string -- field must be defined after class
local foo = {}

---@deprecated
---@type string
foo.example2 = nil

print(foo)
print(foo.example) -- cant mark as deprecated
print(foo.example2)


---@class foo3
---@field example string
---@deprecated -- breaks the local class declaration, and does nothing
local foo = {}

---@deprecated
---@type string
foo.example2 = nil

print(foo)
print(foo.example) -- cant mark as deprecated
print(foo.example2)


---@deprecated
---@class gfoo
---@field example string
gfoo = {}

---@deprecated
---@type string
gfoo.example2 = nil

print(gfoo)
print(gfoo.example) -- cant mark as deprecated
print(gfoo.example2) -- deprecated as expected, but the whole class deprecated, so field is skipped visually


---@class gfoo2
---@deprecated -- still works for class
---@field example string -- field must be defined after class
gfoo = {}

---@deprecated
---@type string
gfoo.example2 = nil

print(gfoo)
print(gfoo.example) -- cant mark as deprecated
print(gfoo.example2) -- deprecated as expected, but the whole class deprecated, so field is skipped visually


---@class gfoo3
---@field example string
---@deprecated -- still works for class
gfoo = {}

---@deprecated
---@type string
gfoo.example2 = nil

print(gfoo)
print(gfoo.example) -- cant mark as deprecated
print(gfoo.example2) -- deprecated as expected, but the whole class deprecated, so field is skipped visually

[tomlau10]

From luals wiki, the @deprecated only (officially) supports marking functions: https://luals.github.io/wiki/annotations/#deprecated

Though it works on table fields to some extend:

---@class foo
---@field example string
local foo = {}
foo.example = nil   ---@deprecated this is the deprecate msg

print(foo.example)  --> Deprecated.(this is the deprecate msg)
--> no need @type, it's already `(field) foo.example: string`

---

However there is another greater problem 😕

• if that field has another assignment statement without the @deprecate
• => the whole field becomes non-deprecate ...

---@class foo
---@field example string
local foo = {}
foo.example = nil   ---@deprecated this is the deprecate msg

print(foo.example)  --> the deprecate warning is gone ...

-- because the follow assignment statement to that field doesn't have @deprecate
foo.example = nil

[rhys-vdw]

foo.example = nil   ---@deprecated this is the deprecate msg

btw, this ability to use a deprecation message is not documented. Is it correct?

[tomlau10]

btw, this ability to use a deprecation message is not documented. Is it correct?

I don't know where I see the example usage of this, but you're right it's not documented in the wiki currently 🙈