Deprecation messages should show informative message (eg the corresponding documentation comment)

[timotheecour]

[enhancement request]

Deprecation messages should show informative message (eg the corresponding documentation comment)

eg:

proc writeLn*(s: Stream, args: varargs[string, `$`]) {.deprecated.} =
    ## **Deprecated since version 0.11.4:** Use **writeLine** instead.
    ... 

using writeLn in code produces this:
Warning: writeLn is deprecated [Deprecated]

it should show something like this instead:

• option 1: put the whole documentation comment of deprecated function:
  Warning: writeLn is deprecated ; **Deprecated since version 0.11.4:** Use **writeLine** instead. [Deprecated]
• option 2: (if easy to in a general way):
  Warning: writeLn is deprecated ; Use **writeLine** instead. [Deprecated]
• option 3:
  Warning: writeLn is deprecated (defined at file:line) [Deprecated]

[GULPF]

Araq actually implemented this syntax a while back, but it's not documented anywhere afaik and doesn't work for variables:

proc foo*() {.deprecated: "Use bar instead".}=
    discard


foo() # Warning: Use bar instead; foo is deprecated

var baz {.deprecated: "A Comment" .}: int # Error: list of key:value pairs expected

[PMunch]

Yeah, the deprecated pragma is quite under-documented: https://nim-lang.org/docs/manual.html#pragmas-deprecated-pragma. Just stumbled upon this issue myself after mratsim on IRC tipped me of this. I thought it was possible to do this but not seeing it in the documentation made me wonder.

[timotheecour]

thanks @awr1 for pushing #8783 to document proc thing(x: bool) {.deprecated: "See arguments of otherThing()".}

the other points remain as TODO, I think.

[Araq]

Come on, {.deprecated: "Use bar instead".} is perfectly fine.