Render deprecated pragmas (#8886)

* Render deprecated pragmas * fix the expected html * clean up the documentation regarding deprecations * fix typo * fix system.nim * fix random
2026-04-19 05:50:30 +00:00 · 2019-06-03 10:15:20 +02:00
parent 64518380a5
commit 7d217a71d3
21 changed files with 180 additions and 117 deletions
--- a/compiler/docgen.nim
+++ b/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
--- a/compiler/trees.nim
+++ b/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]
--- a/config/nimdoc.cfg
+++ b/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>
--- a/lib/core/macros.nim
+++ b/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.} =
-  ## **Deprecated since version 0.18.1**; All functionality is defined on ``NimNode``.
+proc ident*(n: NimNode): NimIdent {.magic: "NIdent", noSideEffect, deprecated:
+  "Deprecated since version 0.18.1; All functionality is defined on 'NimNode'.".}

-proc symbol*(n: NimNode): NimSym {.magic: "NSymbol", noSideEffect, deprecated.}
-  ## **Deprecated since version 0.18.1**; All functionality is defined on ``NimNode``.
+proc symbol*(n: NimNode): NimSym {.magic: "NSymbol", noSideEffect, deprecated:
+  "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.}
-  ## **Deprecated since version 0.18.1**; Generate a new ``NimNode`` with ``genSym`` instead.
+proc `symbol=`*(n: NimNode, val: NimSym) {.magic: "NSetSymbol", noSideEffect, deprecated:
+  "Deprecated since version 0.18.1; Generate a new 'NimNode' with 'genSym' instead.".}

-proc `ident=`*(n: NimNode, val: NimIdent) {.magic: "NSetIdent", noSideEffect, deprecated.}
-  ## **Deprecated since version 0.18.1**; Generate a new ``NimNode`` with ``ident(string)`` instead.
+proc `ident=`*(n: NimNode, val: NimIdent) {.magic: "NSetIdent", noSideEffect, deprecated:
+  "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,
-  deprecated: "use varargs[untyped] in the macro prototype instead".}
+proc callsite*(): NimNode {.magic: "NCallSite", benign, deprecated:
+  "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,
-              args: varargs[NimNode]): NimNode {.compileTime, deprecated.} =
+proc newCall*(theProc: NimIdent, 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.} =
-  ## **Deprecated since version 0.18.1**; Use one of ``nestList(NimNode, ...)`` instead.
+proc nestList*(theProc: NimIdent, x: NimNode): NimNode {.compileTime, deprecated:
+  "Deprecated since v0.18.1; use one of 'nestList(NimNode, ...)' instead.".} =
  nestList(newIdentNode(theProc), x)

 {.pop.}
--- a/lib/impure/re.nim
+++ b/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,
--- a/lib/pure/algorithm.nim
+++ b/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.} =
-  ## **Deprecated since version 0.18.1**; Use `binarySearch proc
-  ## <#binarySearch,openArray[T],T>`_ instead.
+proc smartBinarySearch*[T](a: openArray[T], key: T): int {.deprecated:
+  "Deprecated since v0.18.1; Use 'binarySearch'".} =
  binarySearch(a, key, cmp[T])

 const
--- a/lib/pure/asyncdispatch.nim
+++ b/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()
--- a/lib/pure/collections/heapqueue.nim
+++ b/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.} =
-  ## **Deprecated since v0.20.0:** use ``initHeapQueue`` instead.
+proc newHeapQueue*[T](): HeapQueue[T] {.deprecated:
+  "Deprecated since v0.20.0: use 'initHeapQueue' instead.".} =
  initHeapQueue[T]()

-proc newHeapQueue*[T](heap: var HeapQueue[T]) {.deprecated.} =
-  ## **Deprecated since v0.20.0:** use ``clear`` instead.
+proc newHeapQueue*[T](heap: var HeapQueue[T]) {.deprecated:
+  "Deprecated since v0.20.0: use 'clear' instead.".} =
  heap.clear()

 when isMainModule:
--- a/lib/pure/collections/sets.nim
+++ b/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,int>`_.
+     "Deprecated since v0.20, use 'initHashSet'"} = initHashSet[A](initialSize)

 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,openArray[A]>`_.
+     "Deprecated since v0.20, use 'toHashSet'"} = toHashSet[A](keys)

 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>`_).
--- a/lib/pure/collections/sharedlist.nim
+++ b/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.} =
-  ## Deprecated. Use `init` instead.
+proc initSharedList*[A](): SharedList[A] {.deprecated: "use 'init' instead".} =
  ## This is not posix compliant, may introduce undefined behavior.
  initLock result.lock
  result.head = nil
--- a/lib/pure/collections/sharedtables.nim
+++ b/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.} =
-  ## Deprecated. Use `init` instead.
+proc initSharedTable*[A, B](initialSize=64): SharedTable[A, B] {.deprecated:
+  "use 'init' instead".} =
  ## This is not posix compliant, may introduce undefined behavior.
  assert isPowerOfTwo(initialSize)
  result.counter = 0
--- a/lib/pure/json.nim
+++ b/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".} =
-  ## **Deprecated since v0.18.2:** use ``getInt`` or ``getBiggestInt`` instead.
+proc getNum*(n: JsonNode, default: BiggestInt = 0): BiggestInt {.deprecated:
+  "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".} =
-  ## **Deprecated since v0.18.2:** use ``getFloat`` instead.
+proc getFNum*(n: JsonNode, default: float = 0.0): float {.deprecated:
+  "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".} =
-  ## **Deprecated since v0.18.2:** use ``getBool`` instead.
+proc getBVal*(n: JsonNode, default: bool = false): bool {.deprecated:
+  "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)
-  ## **Deprecated:** use `hasKey` instead.
+proc existsKey*(node: JsonNode, key: string): bool {.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
--- a/lib/pure/math.nim
+++ b/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".} =
-  ## **Deprecated since version v0.20.0**: Use ``bitops.countSetBits`` instead.
+proc countBits32*(n: int32): int {.noSideEffect, deprecated:
+  "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: float64): float64 {.deprecated: "use mod instead", importc: "fmod", header: "<math.h>".}
-    ## **Deprecated since version 0.19.0**: Use the `mod proc
-    ## <#mod,float64,float64>`_ instead.
-    ##
+  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: "Deprecated since v0.19.0; use 'mod' instead", importc: "fmod", header: "<math.h>".}
    ## 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".} =
-  ## **Deprecated:** use `strformat module <strformat.html>`_
-  ##
+proc round*[T: float32|float64](x: T, places: int): T {.deprecated: "use strformat module instead".} =
  ## Decimal rounding on a binary floating point number.
  ##
  ## This function is NOT reliable. Floating point numbers cannot hold
--- a/lib/pure/nativesockets.nim
+++ b/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) =
--- a/lib/pure/random.nim
+++ b/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.} =
-  ## **Deprecated since version 0.18.0:**
-  ## Use `rand(int)<#rand,int>`_ instead.
+proc random*(max: int): int {.benign, deprecated:
+  "Deprecated since v0.18.0; use 'rand' istead".} =
  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.} =
-  ## **Deprecated since version 0.18.0:**
-  ## Use `rand(float)<#rand,float>`_ instead.
+proc random*(max: float): float {.benign, deprecated:
+  "Deprecated since v0.18.0; use 'rand' istead".} =
  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.} =
-  ## **Deprecated since version 0.18.0:**
-  ## Use `rand[T](HSlice[T, T])<#rand,HSlice[T,T]>`_ instead.
+proc random*[T](x: HSlice[T, T]): T {.deprecated:
+  "Deprecated since v0.18.0; use 'rand' instead".} =
  result = T(random(x.b - x.a)) + x.a

-proc random*[T](a: openArray[T]): T {.deprecated.} =
-  ## **Deprecated since version 0.18.0:**
-  ## Use `sample[T](openArray[T])<#sample,openArray[T]>`_ instead.
+proc random*[T](a: openArray[T]): T {.deprecated:
+  "Deprecated since v0.18.0; use 'sample' 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.} =
-  ## **Deprecated since version 0.20.0:**
-  ## Use `sample[T](Rand, openArray[T])<#sample,Rand,openArray[T]>`_ instead.
+proc rand*[T](r: var Rand; a: openArray[T]): T {.deprecated:
+  "Deprecated since v0.20.0; use 'sample' 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.} =
-  ## **Deprecated since version 0.20.0:**
-  ## Use `sample[T](openArray[T])<#sample,openArray[T]>`_ instead.
+proc rand*[T](a: openArray[T]): T {.deprecated:
+  "Deprecated since v0.20.0; use 'sample' instead".} =
  result = a[rand(a.low..a.high)]

 proc sample*[T](r: var Rand; s: set[T]): T =
--- a/lib/system.nim
+++ b/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.
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
 proc getRefcount*(x: string): int {.importc: "getRefcount", noSideEffect,
-  deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
-  ## Deprecated.
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
 proc getRefcount*[T](x: seq[T]): int {.importc: "getRefcount", noSideEffect,
-  deprecated: "the refcount never was reliable, the GC does not use traditional refcounting".}
-  ## Deprecated.
+  deprecated: "the refcount was never reliable, the GC does not use traditional refcounting".}
  ##
  ## 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):
--- a/nimdoc/test_out_index_dot_html/expected/index.html
+++ b/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>
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/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>
--- a/nimdoc/testproject/expected/testproject.html
+++ b/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>
--- a/nimdoc/testproject/expected/theindex.html
+++ b/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>
--- a/nimdoc/testproject/testproject.nim
+++ b/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 =