Render deprecated pragmas (#8886)

* Render deprecated pragmas
* fix the expected html
* clean up the documentation regarding deprecations
* fix typo
* fix system.nim
* fix random

compiler/docgen.nim

@@ -17,7 +17,7 @@ import
   packages/docutils/rst, packages/docutils/rstgen,
   packages/docutils/highlite, json, xmltree, cgi, trees, types,
   typesrenderer, astalgo, modulepaths, lineinfos, sequtils, intsets,
-  pathutils
+  pathutils, trees
 
 const
   exportSection = skField
@@ -25,7 +25,8 @@ const
 type
   TSections = array[TSymKind, Rope]
   TDocumentor = object of rstgen.RstGenerator
-    modDesc: Rope           # module description
+    modDesc: Rope       # module description
+    modDeprecationMsg: Rope
     toc, section: TSections
     indexValFilename: string
     analytics: string  # Google Analytics javascript, "" if doesn't exist
@@ -610,6 +611,23 @@ proc docstringSummary(rstText: string): string =
     result.delete(pos, last)
     result.add("…")
 
+proc genDeprecationMsg(d: PDoc, n: PNode): Rope =
+  ## Given a nkPragma wDeprecated node output a well-formatted section
+  if n == nil: return
+
+  case n.safeLen:
+  of 0: # Deprecated w/o any message
+    result = ropeFormatNamedVars(d.conf,
+      getConfigVar(d.conf, "doc.deprecationmsg"), ["label", "message"],
+      [~"Deprecated", nil])
+  of 2: # Deprecated w/ a message
+    if n[1].kind in {nkStrLit..nkTripleStrLit}:
+      result = ropeFormatNamedVars(d.conf,
+        getConfigVar(d.conf, "doc.deprecationmsg"), ["label", "message"],
+        [~"Deprecated:", rope(xmltree.escape(n[1].strVal))])
+  else:
+    doAssert false
+
 proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
   if not isVisible(d, nameNode): return
   let
@@ -631,6 +649,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
       break
     plainName.add(literal)
 
+  var pragmaNode: PNode = nil
+  if n.isCallable and n.sons[pragmasPos].kind != nkEmpty:
+    pragmaNode = findPragma(n.sons[pragmasPos], wDeprecated)
+
   inc(d.id)
   let
     plainNameRope = rope(xmltree.escape(plainName.strip))
@@ -642,6 +664,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
     symbolOrId = d.newUniquePlainSymbol(complexSymbol)
     symbolOrIdRope = symbolOrId.rope
     symbolOrIdEncRope = encodeUrl(symbolOrId).rope
+    deprecationMsgRope = genDeprecationMsg(d, pragmaNode)
 
   nodeToHighlightedHtml(d, n, result, {renderNoBody, renderNoComments,
     renderDocComments, renderSyms}, symbolOrIdEncRope)
@@ -666,9 +689,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind) =
 
   add(d.section[k], ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.item"),
     ["name", "header", "desc", "itemID", "header_plain", "itemSym",
-      "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc"],
+      "itemSymOrID", "itemSymEnc", "itemSymOrIDEnc", "seeSrc", "deprecationMsg"],
     [nameRope, result, comm, itemIDRope, plainNameRope, plainSymbolRope,
-      symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, seeSrcRope]))
+      symbolOrIdRope, plainSymbolEncRope, symbolOrIdEncRope, seeSrcRope,
+      deprecationMsgRope]))
 
   let external = d.destFile.relativeTo(d.conf.outDir, '/').changeFileExt(HtmlExt).string
 
@@ -821,6 +845,9 @@ proc documentRaises*(cache: IdentCache; n: PNode) =
 
 proc generateDoc*(d: PDoc, n, orig: PNode) =
   case n.kind
+  of nkPragma:
+    let pragmaNode = findPragma(n, wDeprecated)
+    add(d.modDeprecationMsg, genDeprecationMsg(d, pragmaNode))
   of nkCommentStmt: add(d.modDesc, genComment(d, n))
   of nkProcDef:
     when useEffectSystem: documentRaises(d.cache, n)
@@ -993,17 +1020,17 @@ proc genOutFile(d: PDoc): Rope =
                  elif d.hasToc: "doc.body_toc"
                  else: "doc.body_no_toc"
   content = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, bodyname), ["title",
-      "tableofcontents", "moduledesc", "date", "time", "content"],
+      "tableofcontents", "moduledesc", "date", "time", "content", "deprecationMsg"],
       [title.rope, toc, d.modDesc, rope(getDateStr()),
-      rope(getClockStr()), code])
+      rope(getClockStr()), code, d.modDeprecationMsg])
   if optCompileOnly notin d.conf.globalOptions:
     # XXX what is this hack doing here? 'optCompileOnly' means raw output!?
     code = ropeFormatNamedVars(d.conf, getConfigVar(d.conf, "doc.file"), ["title",
         "tableofcontents", "moduledesc", "date", "time",
-        "content", "author", "version", "analytics"],
+        "content", "author", "version", "analytics", "deprecationMsg"],
         [title.rope, toc, d.modDesc, rope(getDateStr()),
                      rope(getClockStr()), content, d.meta[metaAuthor].rope,
-                     d.meta[metaVersion].rope, d.analytics.rope])
+                     d.meta[metaVersion].rope, d.analytics.rope, d.modDeprecationMsg])
   else:
     code = content
   result = code

compiler/trees.nim

@@ -120,6 +120,12 @@ proc whichPragma*(n: PNode): TSpecialWord =
   let key = if n.kind in nkPragmaCallKinds and n.len > 0: n.sons[0] else: n
   if key.kind == nkIdent: result = whichKeyword(key.ident)
 
+proc findPragma*(n: PNode, which: TSpecialWord): PNode =
+  if n.kind == nkPragma:
+    for son in n:
+      if whichPragma(son) == which:
+        return son
+
 proc effectSpec*(n: PNode, effectType: TSpecialWord): PNode =
   for i in 0 ..< sonsLen(n):
     var it = n.sons[i]

config/nimdoc.cfg

@@ -41,6 +41,7 @@ doc.item = """
 <a id="$itemSymOrID"></a>
 <dt><pre>$header</pre></dt>
 <dd>
+$deprecationMsg
 $desc
 $seeSrc
 </dd>
@@ -68,6 +69,12 @@ class="link-seesrc" target="_blank">Source</a>
 <a href="${url}/edit/${devel}/${path}#L${line}" class="link-seesrc" target="_blank" >Edit</a>
 """
 
+doc.deprecationmsg = """
+  <div class="deprecation-message">
+    <b>$label</b> $message
+  </div>
+"""
+
 doc.toc = """
 <ul class="simple simple-toc" id="toc-list">
 $content
@@ -98,6 +105,7 @@ doc.body_toc = """
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  $deprecationMsg
   <p class="module-desc">$moduledesc</p>
   $content
   </div>
@@ -140,6 +148,7 @@ doc.body_toc_group = """
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  $deprecationMsg
   <p class="module-desc">$moduledesc</p>
   $content
   </div>
@@ -170,6 +179,7 @@ doc.body_toc_group = """
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  $deprecationMsg
   <p class="module-desc">$moduledesc</p>
   $content
   </div>

lib/core/macros.nim

@@ -139,24 +139,24 @@ const
 
 {.push warnings: off.}
 
-proc `!`*(s: string): NimIdent {.magic: "StrToIdent", noSideEffect, deprecated.}
+proc `!`*(s: string): NimIdent {.magic: "StrToIdent", noSideEffect, deprecated:
+  "Deprecated since version 0.18.0: Use 'ident' or 'newIdentNode' instead.".}
   ## constructs an identifier from the string `s`
-  ## **Deprecated since version 0.18.0**: Use ``ident`` or ``newIdentNode`` instead.
 
-proc toNimIdent*(s: string): NimIdent {.magic: "StrToIdent", noSideEffect, deprecated.}
+proc toNimIdent*(s: string): NimIdent {.magic: "StrToIdent", noSideEffect, deprecated:
+  "Deprecated since version 0.18.0: Use 'ident' or 'newIdentNode' instead.".}
   ## constructs an identifier from the string `s`
-  ## **Deprecated since version 0.18.1**; Use ``ident`` or ``newIdentNode`` instead.
 
-proc `==`*(a, b: NimIdent): bool {.magic: "EqIdent", noSideEffect, deprecated.}
+proc `==`*(a, b: NimIdent): bool {.magic: "EqIdent", noSideEffect, deprecated:
+  "Deprecated since version 0.18.1; Use '==' on 'NimNode' instead.".}
   ## compares two Nim identifiers
-  ## **Deprecated since version 0.18.1**; Use ``==`` on ``NimNode`` instead.
 
 proc `==`*(a, b: NimNode): bool {.magic: "EqNimrodNode", noSideEffect.}
   ## compares two Nim nodes
 
-proc `==`*(a, b: NimSym): bool {.magic: "EqNimrodNode", noSideEffect, deprecated.}
+proc `==`*(a, b: NimSym): bool {.magic: "EqNimrodNode", noSideEffect, deprecated:
+  "Deprecated since version 0.18.1; Use '==(NimNode, NimNode)' instead.".}
   ## compares two Nim symbols
-  ## **Deprecated since version 0.18.1**; Use ``==(NimNode, NimNode)`` instead.
 
 {.pop.}
 
@@ -231,11 +231,11 @@ proc floatVal*(n: NimNode): BiggestFloat {.magic: "NFloatVal", noSideEffect.}
 
 {.push warnings: off.}
 
-proc ident*(n: NimNode): NimIdent {.magic: "NIdent", noSideEffect, deprecated.} =
+proc ident*(n: NimNode): NimIdent {.magic: "NIdent", noSideEffect, deprecated:
-  ## **Deprecated since version 0.18.1**; All functionality is defined on ``NimNode``.
+  "Deprecated since version 0.18.1; All functionality is defined on 'NimNode'.".}
 
-proc symbol*(n: NimNode): NimSym {.magic: "NSymbol", noSideEffect, deprecated.}
+proc symbol*(n: NimNode): NimSym {.magic: "NSymbol", noSideEffect, deprecated:
-  ## **Deprecated since version 0.18.1**; All functionality is defined on ``NimNode``.
+  "Deprecated since version 0.18.1; All functionality is defined on 'NimNode'.".}
 
 proc getImpl*(s: NimSym): NimNode {.magic: "GetImpl", noSideEffect, deprecated: "use `getImpl: NimNode -> NimNode` instead".}
 
@@ -246,13 +246,13 @@ when defined(nimSymKind):
     ## retrieve the implementation of `symbol`. `symbol` can be a
     ## routine or a const.
 
-  proc `$`*(i: NimIdent): string {.magic: "NStrVal", noSideEffect, deprecated.}
+  proc `$`*(i: NimIdent): string {.magic: "NStrVal", noSideEffect, deprecated:
+    "Deprecated since version 0.18.1; Use 'strVal' instead.".}
     ## converts a Nim identifier to a string
-    ## **Deprecated since version 0.18.1**; Use ``strVal`` instead.
 
-  proc `$`*(s: NimSym): string {.magic: "NStrVal", noSideEffect, deprecated.}
+  proc `$`*(s: NimSym): string {.magic: "NStrVal", noSideEffect, deprecated:
+    "Deprecated since version 0.18.1; Use 'strVal' instead.".}
     ## converts a Nim symbol to a string
-    ## **Deprecated since version 0.18.1**; Use ``strVal`` instead.
 
 else: # bootstrapping substitute
   proc getImpl*(symbol: NimNode): NimNode =
@@ -375,11 +375,11 @@ proc `floatVal=`*(n: NimNode, val: BiggestFloat) {.magic: "NSetFloatVal", noSide
 
 {.push warnings: off.}
 
-proc `symbol=`*(n: NimNode, val: NimSym) {.magic: "NSetSymbol", noSideEffect, deprecated.}
+proc `symbol=`*(n: NimNode, val: NimSym) {.magic: "NSetSymbol", noSideEffect, deprecated:
-  ## **Deprecated since version 0.18.1**; Generate a new ``NimNode`` with ``genSym`` instead.
+  "Deprecated since version 0.18.1; Generate a new 'NimNode' with 'genSym' instead.".}
 
-proc `ident=`*(n: NimNode, val: NimIdent) {.magic: "NSetIdent", noSideEffect, deprecated.}
+proc `ident=`*(n: NimNode, val: NimIdent) {.magic: "NSetIdent", noSideEffect, deprecated:
-  ## **Deprecated since version 0.18.1**; Generate a new ``NimNode`` with ``ident(string)`` instead.
+  "Deprecated since version 0.18.1; Generate a new 'NimNode' with 'ident(string)' instead.".}
 
 {.pop.}
 
@@ -483,10 +483,9 @@ proc genSym*(kind: NimSymKind = nskLet; ident = ""): NimNode {.
   ## generates a fresh symbol that is guaranteed to be unique. The symbol
   ## needs to occur in a declaration context.
 
-proc callsite*(): NimNode {.magic: "NCallSite", benign,
+proc callsite*(): NimNode {.magic: "NCallSite", benign, deprecated:
-  deprecated: "use varargs[untyped] in the macro prototype instead".}
+  "Deprecated since v0.18.1; use varargs[untyped] in the macro prototype instead".}
   ## returns the AST of the invocation expression that invoked this macro.
-  ## **Deprecated since version 0.18.1**.
 
 proc toStrLit*(n: NimNode): NimNode {.compileTime.} =
   ## converts the AST `n` to the concrete Nim code and wraps that
@@ -625,12 +624,10 @@ proc newCall*(theProc: NimNode,
 
 {.push warnings: off.}
 
-proc newCall*(theProc: NimIdent,
+proc newCall*(theProc: NimIdent, args: varargs[NimNode]): NimNode {.compileTime, deprecated:
-              args: varargs[NimNode]): NimNode {.compileTime, deprecated.} =
+  "Deprecated since v0.18.1; use 'newCall(string, ...)' or 'newCall(NimNode, ...)' instead".} =
   ## produces a new call node. `theProc` is the proc that is called with
   ## the arguments ``args[0..]``.
-  ## **Deprecated since version 0.18.1**; Use ``newCall(string, ...)``,
-  ## or ``newCall(NimNode, ...)`` instead.
   result = newNimNode(nnkCall)
   result.add(newIdentNode(theProc))
   result.add(args)
@@ -796,8 +793,8 @@ proc nestList*(op: NimNode; pack: NimNode; init: NimNode): NimNode {.compileTime
 
 {.push warnings: off.}
 
-proc nestList*(theProc: NimIdent, x: NimNode): NimNode {.compileTime, deprecated.} =
+proc nestList*(theProc: NimIdent, x: NimNode): NimNode {.compileTime, deprecated:
-  ## **Deprecated since version 0.18.1**; Use one of ``nestList(NimNode, ...)`` instead.
+  "Deprecated since v0.18.1; use one of 'nestList(NimNode, ...)' instead.".} =
   nestList(newIdentNode(theProc), x)
 
 {.pop.}

lib/impure/re.nim

@@ -485,10 +485,10 @@ proc multiReplace*(s: string, subs: openArray[
   add(result, substr(s, i))
 
 proc parallelReplace*(s: string, subs: openArray[
-                      tuple[pattern: Regex, repl: string]]): string {.deprecated.} =
+  tuple[pattern: Regex, repl: string]]): string {.deprecated:
+  "Deprecated since v0.18.0: Use ``multiReplace`` instead.".} =
   ## Returns a modified copy of ``s`` with the substitutions in ``subs``
   ## applied in parallel.
-  ## **Deprecated since version 0.18.0**: Use ``multiReplace`` instead.
   result = multiReplace(s, subs)
 
 proc transformFile*(infile, outfile: string,

lib/pure/algorithm.nim

@@ -221,9 +221,8 @@ proc binarySearch*[T](a: openArray[T], key: T): int =
     assert binarySearch([0, 1, 4, 2, 3], 4) == 2
   binarySearch(a, key, cmp[T])
 
-proc smartBinarySearch*[T](a: openArray[T], key: T): int {.deprecated.} =
+proc smartBinarySearch*[T](a: openArray[T], key: T): int {.deprecated:
-  ## **Deprecated since version 0.18.1**; Use `binarySearch proc
+  "Deprecated since v0.18.1; Use 'binarySearch'".} =
-  ## <#binarySearch,openArray[T],T>`_ instead.
   binarySearch(a, key, cmp[T])
 
 const

lib/pure/asyncdispatch.nim

@@ -1840,8 +1840,7 @@ proc waitFor*[T](fut: Future[T]): T =
 
   fut.read
 
-proc setEvent*(ev: AsyncEvent) {.deprecated.} =
+proc setEvent*(ev: AsyncEvent) {.deprecated:
+  "Deprecated since v0.18.0: Use 'trigger' instead.".} =
   ## Set event ``ev`` to signaled state.
-  ##
-  ## **Deprecated since v0.18.0:** Use ``trigger`` instead.
   ev.trigger()

lib/pure/collections/heapqueue.nim

@@ -176,12 +176,12 @@ proc `$`*[T](heap: HeapQueue[T]): string =
     result.addQuoted(x)
   result.add("]")
 
-proc newHeapQueue*[T](): HeapQueue[T] {.deprecated.} =
+proc newHeapQueue*[T](): HeapQueue[T] {.deprecated:
-  ## **Deprecated since v0.20.0:** use ``initHeapQueue`` instead.
+  "Deprecated since v0.20.0: use 'initHeapQueue' instead.".} =
   initHeapQueue[T]()
 
-proc newHeapQueue*[T](heap: var HeapQueue[T]) {.deprecated.} =
+proc newHeapQueue*[T](heap: var HeapQueue[T]) {.deprecated:
-  ## **Deprecated since v0.20.0:** use ``clear`` instead.
+  "Deprecated since v0.20.0: use 'clear' instead.".} =
   heap.clear()
 
 when isMainModule:

lib/pure/collections/sets.nim

@@ -604,17 +604,13 @@ proc rightSize*(count: Natural): int {.inline.} =
 
 
 proc initSet*[A](initialSize = defaultInitialSize): HashSet[A] {.deprecated:
-     "Deprecated since v0.20, use `initHashSet`"} = initHashSet[A](initialSize)
+     "Deprecated since v0.20, use 'initHashSet'"} = initHashSet[A](initialSize)
-  ## Deprecated since v0.20, use `initHashSet <#initHashSet,int>`_.
 
 proc toSet*[A](keys: openArray[A]): HashSet[A] {.deprecated:
-     "Deprecated since v0.20, use `toHashSet`"} = toHashSet[A](keys)
+     "Deprecated since v0.20, use 'toHashSet'"} = toHashSet[A](keys)
-  ## Deprecated since v0.20, use `toHashSet <#toHashSet,openArray[A]>`_.
 
 proc isValid*[A](s: HashSet[A]): bool {.deprecated:
      "Deprecated since v0.20; sets are initialized by default"} =
-  ## **Deprecated since v0.20; sets are initialized by default**
-  ##
   ## Returns `true` if the set has been initialized (with `initHashSet proc
   ## <#initHashSet,int>`_ or `init proc <#init,HashSet[A],int>`_).
   ##
@@ -942,7 +938,6 @@ iterator pairs*[A](s: OrderedSet[A]): tuple[a: int, b: A] =
 
 proc isValid*[A](s: OrderedSet[A]): bool {.deprecated:
      "Deprecated since v0.20; sets are initialized by default"} =
-  ## **Deprecated since v0.20; sets are initialized by default**
   ##
   ## Returns `true` if the set has been initialized (with `initHashSet proc
   ## <#initOrderedSet,int>`_ or `init proc <#init,OrderedSet[A],int>`_).

lib/pure/collections/sharedlist.nim

@@ -92,8 +92,7 @@ proc deinitSharedList*[A](t: var SharedList[A]) =
   clear(t)
   deinitLock t.lock
 
-proc initSharedList*[A](): SharedList[A] {.deprecated.} =
+proc initSharedList*[A](): SharedList[A] {.deprecated: "use 'init' instead".} =
-  ## Deprecated. Use `init` instead.
   ## This is not posix compliant, may introduce undefined behavior.
   initLock result.lock
   result.head = nil

lib/pure/collections/sharedtables.nim

@@ -219,8 +219,8 @@ proc deinitSharedTable*[A, B](t: var SharedTable[A, B]) =
   deallocShared(t.data)
   deinitLock t.lock
 
-proc initSharedTable*[A, B](initialSize=64): SharedTable[A, B] {.deprecated.} =
+proc initSharedTable*[A, B](initialSize=64): SharedTable[A, B] {.deprecated:
-  ## Deprecated. Use `init` instead.
+  "use 'init' instead".} =
   ## This is not posix compliant, may introduce undefined behavior.
   assert isPowerOfTwo(initialSize)
   result.counter = 0

lib/pure/json.nim

@@ -239,8 +239,8 @@ proc getBiggestInt*(n: JsonNode, default: BiggestInt = 0): BiggestInt =
   if n.isNil or n.kind != JInt: return default
   else: return n.num
 
-proc getNum*(n: JsonNode, default: BiggestInt = 0): BiggestInt {.deprecated: "use getInt or getBiggestInt instead".} =
+proc getNum*(n: JsonNode, default: BiggestInt = 0): BiggestInt {.deprecated:
-  ## **Deprecated since v0.18.2:** use ``getInt`` or ``getBiggestInt`` instead.
+  "Deprecated since v0.18.2; use 'getInt' or 'getBiggestInt' instead".} =
   getBiggestInt(n, default)
 
 proc getFloat*(n: JsonNode, default: float = 0.0): float =
@@ -253,8 +253,8 @@ proc getFloat*(n: JsonNode, default: float = 0.0): float =
   of JInt: return float(n.num)
   else: return default
 
-proc getFNum*(n: JsonNode, default: float = 0.0): float {.deprecated: "use getFloat instead".} =
+proc getFNum*(n: JsonNode, default: float = 0.0): float {.deprecated:
-  ## **Deprecated since v0.18.2:** use ``getFloat`` instead.
+  "Deprecated since v0.18.2; use 'getFloat' instead".} =
   getFloat(n, default)
 
 proc getBool*(n: JsonNode, default: bool = false): bool =
@@ -264,8 +264,8 @@ proc getBool*(n: JsonNode, default: bool = false): bool =
   if n.isNil or n.kind != JBool: return default
   else: return n.bval
 
-proc getBVal*(n: JsonNode, default: bool = false): bool {.deprecated: "use getBool instead".} =
+proc getBVal*(n: JsonNode, default: bool = false): bool {.deprecated:
-  ## **Deprecated since v0.18.2:** use ``getBool`` instead.
+  "Deprecated since v0.18.2; use 'getBool' instead".} =
   getBool(n, default)
 
 proc getFields*(n: JsonNode,
@@ -511,8 +511,8 @@ proc contains*(node: JsonNode, val: JsonNode): bool =
   assert(node.kind == JArray)
   find(node.elems, val) >= 0
 
-proc existsKey*(node: JsonNode, key: string): bool {.deprecated: "use hasKey instead".} = node.hasKey(key)
+proc existsKey*(node: JsonNode, key: string): bool {.deprecated: "use 'hasKey' instead".} =
-  ## **Deprecated:** use `hasKey` instead.
+  node.hasKey(key)
 
 proc `{}`*(node: JsonNode, keys: varargs[string]): JsonNode =
   ## Traverses the node and gets the given value. If any of the

lib/pure/math.nim

@@ -188,8 +188,8 @@ proc nextPowerOfTwo*(x: int): int {.noSideEffect.} =
   result = result or (result shr 1)
   result += 1 + ord(x<=0)
 
-proc countBits32*(n: int32): int {.noSideEffect, deprecated: "use bitops.countSetBits instead".} =
+proc countBits32*(n: int32): int {.noSideEffect, deprecated:
-  ## **Deprecated since version v0.20.0**: Use ``bitops.countSetBits`` instead.
+  "Deprecated since v0.20.0; use 'bitops.countSetBits' instead".} =
   runnableExamples:
     doAssert countBits32(7) == 3
     doAssert countBits32(8) == 1
@@ -594,11 +594,10 @@ when not defined(JS): # C
       ##  echo gamma(11.0) # 3628800.0
       ##  echo gamma(-1.0) # nan
     proc tgamma*(x: float32): float32
-      {.deprecated: "use gamma instead", importc: "tgammaf", header: "<math.h>".}
+      {.deprecated: "Deprecated since v0.19.0; use 'gamma' instead", importc: "tgammaf", header: "<math.h>".}
     proc tgamma*(x: float64): float64
-      {.deprecated: "use gamma instead", importc: "tgamma", header: "<math.h>".}
+      {.deprecated: "Deprecated since v0.19.0; use 'gamma' instead", importc: "tgamma", header: "<math.h>".}
       ## The gamma function
-      ## **Deprecated since version 0.19.0**: Use ``gamma`` instead.
     proc lgamma*(x: float32): float32 {.importc: "lgammaf", header: "<math.h>".}
     proc lgamma*(x: float64): float64 {.importc: "lgamma", header: "<math.h>".}
       ## Computes the natural log of the gamma function for ``x``.
@@ -729,11 +728,8 @@ when not defined(JS): # C
       ##  echo trunc(PI) # 3.0
       ##  echo trunc(-1.85) # -1.0
 
-  proc fmod*(x, y: float32): float32 {.deprecated: "use mod instead", importc: "fmodf", header: "<math.h>".}
+  proc fmod*(x, y: float32): float32 {.deprecated: "Deprecated since v0.19.0; use 'mod' instead", importc: "fmodf", header: "<math.h>".}
-  proc fmod*(x, y: float64): float64 {.deprecated: "use mod instead", importc: "fmod", header: "<math.h>".}
+  proc fmod*(x, y: float64): float64 {.deprecated: "Deprecated since v0.19.0; use 'mod' instead", importc: "fmod", header: "<math.h>".}
-    ## **Deprecated since version 0.19.0**: Use the `mod proc
-    ## <#mod,float64,float64>`_ instead.
-    ##
     ## Computes the remainder of ``x`` divided by ``y``.
 
   proc `mod`*(x, y: float32): float32 {.importc: "fmodf", header: "<math.h>".}
@@ -772,9 +768,7 @@ else: # JS
     ##  ( 6.5 mod -2.5) ==  1.5
     ##  (-6.5 mod -2.5) == -1.5
 
-proc round*[T: float32|float64](x: T, places: int): T {.deprecated: "use format instead".} =
+proc round*[T: float32|float64](x: T, places: int): T {.deprecated: "use strformat module instead".} =
-  ## **Deprecated:** use `strformat module <strformat.html>`_
-  ##
   ## Decimal rounding on a binary floating point number.
   ##
   ## This function is NOT reliable. Floating point numbers cannot hold

lib/pure/nativesockets.nim

@@ -201,21 +201,17 @@ proc createNativeSocket*(domain: cint, sockType: cint,
 proc newNativeSocket*(domain: Domain = AF_INET,
                       sockType: SockType = SOCK_STREAM,
                       protocol: Protocol = IPPROTO_TCP): SocketHandle
-                      {.deprecated.} =
+                      {.deprecated: "deprecated since v0.18.0; use 'createNativeSocket' instead".} =
   ## Creates a new socket; returns `osInvalidSocket` if an error occurs.
-  ##
-  ## **Deprecated since v0.18.0:** Use ``createNativeSocket`` instead.
   createNativeSocket(domain, sockType, protocol)
 
 proc newNativeSocket*(domain: cint, sockType: cint,
                       protocol: cint): SocketHandle
-                      {.deprecated.} =
+                      {.deprecated: "deprecated since v0.18.0; use 'createNativeSocket' instead".} =
   ## Creates a new socket; returns `osInvalidSocket` if an error occurs.
   ##
   ## Use this overload if one of the enums specified above does
   ## not contain what you need.
-  ##
-  ## **Deprecated since v0.18.0:** Use ``createNativeSocket`` instead.
   createNativeSocket(domain, sockType, protocol)
 
 proc close*(socket: SocketHandle) =

lib/pure/random.nim

@@ -206,17 +206,15 @@ proc skipRandomNumbers*(s: var Rand) =
   s.a0 = s0
   s.a1 = s1
 
-proc random*(max: int): int {.benign, deprecated.} =
+proc random*(max: int): int {.benign, deprecated:
-  ## **Deprecated since version 0.18.0:**
+  "Deprecated since v0.18.0; use 'rand' istead".} =
-  ## Use `rand(int)<#rand,int>`_ instead.
   while true:
     let x = next(state)
     if x < randMax - (randMax mod ui(max)):
       return int(x mod uint64(max))
 
-proc random*(max: float): float {.benign, deprecated.} =
+proc random*(max: float): float {.benign, deprecated:
-  ## **Deprecated since version 0.18.0:**
+  "Deprecated since v0.18.0; use 'rand' istead".} =
-  ## Use `rand(float)<#rand,float>`_ instead.
   let x = next(state)
   when defined(JS):
     result = (float(x) / float(high(uint32))) * max
@@ -224,14 +222,12 @@ proc random*(max: float): float {.benign, deprecated.} =
     let u = (0x3FFu64 shl 52u64) or (x shr 12u64)
     result = (cast[float](u) - 1.0) * max
 
-proc random*[T](x: HSlice[T, T]): T {.deprecated.} =
+proc random*[T](x: HSlice[T, T]): T {.deprecated:
-  ## **Deprecated since version 0.18.0:**
+  "Deprecated since v0.18.0; use 'rand' instead".} =
-  ## Use `rand[T](HSlice[T, T])<#rand,HSlice[T,T]>`_ instead.
   result = T(random(x.b - x.a)) + x.a
 
-proc random*[T](a: openArray[T]): T {.deprecated.} =
+proc random*[T](a: openArray[T]): T {.deprecated:
-  ## **Deprecated since version 0.18.0:**
+  "Deprecated since v0.18.0; use 'sample' instead".} =
-  ## Use `sample[T](openArray[T])<#sample,openArray[T]>`_ instead.
   result = a[random(a.low..a.len)]
 
 proc rand*(r: var Rand; max: Natural): int {.benign.} =
@@ -367,9 +363,8 @@ proc rand*[T: Ordinal or SomeFloat](x: HSlice[T, T]): T =
     doAssert rand(1..6) == 6
   result = rand(state, x)
 
-proc rand*[T](r: var Rand; a: openArray[T]): T {.deprecated.} =
+proc rand*[T](r: var Rand; a: openArray[T]): T {.deprecated:
-  ## **Deprecated since version 0.20.0:**
+  "Deprecated since v0.20.0; use 'sample' instead".} =
-  ## Use `sample[T](Rand, openArray[T])<#sample,Rand,openArray[T]>`_ instead.
   result = a[rand(r, a.low..a.high)]
 
 proc rand*[T: SomeInteger](t: typedesc[T]): T =
@@ -401,9 +396,8 @@ proc rand*[T: SomeInteger](t: typedesc[T]): T =
   else:
     result = cast[T](state.next)
 
-proc rand*[T](a: openArray[T]): T {.deprecated.} =
+proc rand*[T](a: openArray[T]): T {.deprecated:
-  ## **Deprecated since version 0.20.0:**
+  "Deprecated since v0.20.0; use 'sample' instead".} =
-  ## Use `sample[T](openArray[T])<#sample,openArray[T]>`_ instead.
   result = a[rand(a.low..a.high)]
 
 proc sample*[T](r: var Rand; s: set[T]): T =

lib/system.nim

@@ -2487,14 +2487,11 @@ when not defined(js) and not defined(booting) and defined(nimTrMacros):
 
 # undocumented:
 proc getRefcount*[T](x: ref T): int {.importc: "getRefcount", noSideEffect,
-  deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
-  ## Deprecated.
 proc getRefcount*(x: string): int {.importc: "getRefcount", noSideEffect,
-  deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
-  ## Deprecated.
 proc getRefcount*[T](x: seq[T]): int {.importc: "getRefcount", noSideEffect,
-  deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
-  ## Deprecated.
   ##
   ## Retrieves the reference count of an heap-allocated object. The
   ## value is implementation-dependent.
@@ -4221,8 +4218,6 @@ proc addQuoted*[T](s: var string, x: T) =
 when hasAlloc:
   # XXX: make these the default (or implement the NilObject optimization)
   proc safeAdd*[T](x: var seq[T], y: T) {.noSideEffect, deprecated.} =
-    ## **Deprecated**
-    ##
     ## Adds ``y`` to ``x`` unless ``x`` is not yet initialized; in that case,
     ## ``x`` becomes ``@[y]``.
     when defined(nimNoNilSeqs):
@@ -4232,8 +4227,6 @@ when hasAlloc:
       else: x.add(y)
 
   proc safeAdd*(x: var string, y: char) {.noSideEffect, deprecated.} =
-    ## **Deprecated**
-    ##
     ## Adds ``y`` to ``x``. If ``x`` is ``nil`` it is initialized to ``""``.
     when defined(nimNoNilSeqs):
       x.add(y)
@@ -4242,8 +4235,6 @@ when hasAlloc:
       x.add(y)
 
   proc safeAdd*(x: var string, y: string) {.noSideEffect, deprecated.} =
-    ## **Deprecated**
-    ##
     ## Adds ``y`` to ``x`` unless ``x`` is not yet initalized; in that
     ## case, ``x`` becomes ``y``.
     when defined(nimNoNilSeqs):

nimdoc/test_out_index_dot_html/expected/index.html

@@ -820,6 +820,7 @@ function main() {
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  
   <p class="module-desc"></p>
   <div class="section" id="12">
 <h1><a class="toc-backref" href="#12">Procs</a></h1>
@@ -827,6 +828,7 @@ function main() {
 <a id="foo"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#foo"><span class="Identifier">foo</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
 <dd>
+
 I do foo
 
 </dd>

nimdoc/testproject/expected/subdir/subdir_b/utils.html

@@ -844,6 +844,7 @@ function main() {
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  
   <p class="module-desc">
 <h1><a class="toc-backref" id="this-is-now-a-header" href="#this-is-now-a-header">This is now a header</a></h1>
 <h2><a class="toc-backref" id="this-is-now-a-header-next-header" href="#this-is-now-a-header-next-header">Next header</a></h2>
@@ -866,6 +867,7 @@ function main() {
 <dd>
 
 
+
 </dd>
 
 </dl></div>
@@ -875,6 +877,7 @@ function main() {
 <a id="someType_2"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#someType_2"><span class="Identifier">someType</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
 <dd>
+
 constructor.
 
 </dd>
@@ -888,12 +891,14 @@ constructor.
 <dd>
 
 
+
 </dd>
 <a id="bEnum.t"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#bEnum.t"><span class="Identifier">bEnum</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
 <dd>
 
 
+
 </dd>
 
 </dl></div>

nimdoc/testproject/expected/testproject.html

@@ -837,6 +837,10 @@ function main() {
   <ul class="simple simple-toc-section">
       <li><a class="reference" href="#bar%2CT%2CT"
     title="bar[T](a, b: T): T"><wbr />bar<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#baz%2CT%2CT"
+    title="baz[T](a, b: T): T"><wbr />baz<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#buzz%2CT%2CT"
+    title="buzz[T](a, b: T): T"><wbr />buzz<span class="attachedType"></span></a></li>
   <li><a class="reference" href="#isValid%2CT"
     title="isValid[T](x: T): bool"><wbr />is<wbr />Valid<span class="attachedType"></span></a></li>
 
@@ -872,6 +876,7 @@ function main() {
   </div>
   <div class="nine columns" id="content">
   <div id="tocRoot"></div>
+  
   <p class="module-desc">This is the top level module.
 <p><strong class="examples_text">Examples:</strong></p>
 <pre class="listing"><span class="Keyword">import</span>
@@ -893,6 +898,7 @@ function main() {
 <dt><pre><a href="testproject.html#A"><span class="Identifier">A</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">inject</span></span><span class="Other">.}</span></span> <span class="Other">=</span> <span class="Keyword">enum</span>
   <span class="Identifier">aA</span></pre></dt>
 <dd>
+
 The enum A.
 
 </dd>
@@ -900,6 +906,7 @@ The enum A.
 <dt><pre><a href="testproject.html#B"><span class="Identifier">B</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">inject</span></span><span class="Other">.}</span></span> <span class="Other">=</span> <span class="Keyword">enum</span>
   <span class="Identifier">bB</span></pre></dt>
 <dd>
+
 The enum B.
 
 </dd>
@@ -913,6 +920,7 @@ The enum B.
 <dd>
 
 
+
 </dd>
 
 </dl></div>
@@ -924,12 +932,34 @@ The enum B.
 <dd>
 
 
+
+</dd>
+<a id="baz,T,T"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#baz%2CT%2CT"><span class="Identifier">baz</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">deprecated</span></span><span class="Other">.}</span></span></pre></dt>
+<dd>
+  <div class="deprecation-message">
+    <b>Deprecated</b> 
+  </div>
+
+This is deprecated without message.
+
+</dd>
+<a id="buzz,T,T"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#buzz%2CT%2CT"><span class="Identifier">buzz</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">T</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">deprecated</span><span class="Other">:</span> <span class="StringLit">&quot;since v0.20&quot;</span></span><span class="Other">.}</span></span></pre></dt>
+<dd>
+  <div class="deprecation-message">
+    <b>Deprecated:</b> since v0.20
+  </div>
+
+This is deprecated with a message.
+
 </dd>
 <a id="isValid,T"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#isValid%2CT"><span class="Identifier">isValid</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
 <dd>
 
 
+
 </dd>
 
 </dl></div>
@@ -939,6 +969,7 @@ The enum B.
 <a id="someFunc"></a>
 <dt><pre><span class="Keyword">func</span> <a href="#someFunc"><span class="Identifier">someFunc</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
 <dd>
+
 My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</span></tt> here. <a class="reference external" href="https://nim-lang.org">Some link</a>
 
 </dd>
@@ -952,6 +983,7 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 <dd>
 
 
+
 </dd>
 
 </dl></div>
@@ -961,6 +993,7 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 <a id="foo.t,SomeType,SomeType"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#foo.t%2CSomeType%2CSomeType"><span class="Identifier">foo</span></a><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
 <dd>
+
 This does nothing 
 
 </dd>

nimdoc/testproject/expected/theindex.html

@@ -811,10 +811,18 @@ function main() {
           <li><a class="reference external"
           data-doc-search-tag="testproject: bar(): untyped" href="testproject.html#bar.m">testproject: bar(): untyped</a></li>
           </ul></dd>
+<dt><a name="baz" href="#baz"><span>baz:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: baz[T](a, b: T): T" href="testproject.html#baz%2CT%2CT">testproject: baz[T](a, b: T): T</a></li>
+          </ul></dd>
 <dt><a name="bEnum" href="#bEnum"><span>bEnum:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="utils: bEnum(): untyped" href="subdir/subdir_b/utils.html#bEnum.t">utils: bEnum(): untyped</a></li>
           </ul></dd>
+<dt><a name="buzz" href="#buzz"><span>buzz:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: buzz[T](a, b: T): T" href="testproject.html#buzz%2CT%2CT">testproject: buzz[T](a, b: T): T</a></li>
+          </ul></dd>
 <dt><a name="enumValueA" href="#enumValueA"><span>enumValueA:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="SomeType.enumValueA" href="subdir/subdir_b/utils.html#enumValueA">SomeType.enumValueA</a></li>

nimdoc/testproject/testproject.nim

@@ -18,6 +18,14 @@ template foo*(a, b: SomeType) =
 proc bar*[T](a, b: T): T =
   result = a + b
 
+proc baz*[T](a, b: T): T {.deprecated.} =
+  ## This is deprecated without message.
+  result = a + b
+
+proc buzz*[T](a, b: T): T {.deprecated: "since v0.20".} =
+  ## This is deprecated with a message.
+  result = a + b
+
 import std/macros
 
 macro bar*(): untyped =