add a small message to @deprecated

[teto]

maybe this was discussed before but right now I've got a whole lot of functions which I see as @deprecated but I have to look into the source code to see what to replace it with. Would be nice if one could add a message explaining how to fix the deprecation notice ?

[C3pa]

I usually just write at the top of the function description what this function should be replaced with.

For example:

--- **Use `bar()` instead.**
--- Foo description.
--- @deprecated
--- @param a string
function foo(a)
end

[carsakiller]

I think that what C3pa said in combination with #2175 would be satisfactory. Something like the below:

---Replaced by [bar()](lua://someSymbol)
---Original description
---@deprecated
function foo() end

[mycroftjr]

Why on earth does @deprecated not just accept an optional message explaining why/what to use instead?