rename nimEnableHashRef [backport] (#18941)

* rename nimEnableHashRef [backport]
* Apply suggestions from code review

Co-authored-by: konsumlamm <44230978+konsumlamm@users.noreply.github.com>

changelog.md

@@ -64,7 +64,8 @@
   for previous behavior.
 
 - `hashes.hash` can now support `object` and `ref` (can be overloaded in user code),
-  if `-d:nimEnableHashRef` is used.
+  if `-d:nimPreviewHashRef` is used. It is expected that this behavior
+  becomes the new default in upcoming versions.
 
 - `hashes.hash(proc|ptr|ref|pointer)` now calls `hash(int)` and honors `-d:nimIntHash1`,
   `hashes.hash(closure)` has also been improved.

lib/pure/hashes.nim

@@ -51,8 +51,12 @@ runnableExamples:
     h = h !& hash(x.bar)
     result = !$h
 
-## **Note:** If the type has a `==` operator, the following must hold:
+## .. important:: Use `-d:nimPreviewHashRef` to
-## If two values compare equal, their hashes must also be equal.
+##    enable hashing `ref`s. It is expected that this behavior
+##    becomes the new default in upcoming versions.
+##
+## .. note:: If the type has a `==` operator, the following must hold:
+##    If two values compare equal, their hashes must also be equal.
 ##
 ## See also
 ## ========
@@ -236,10 +240,14 @@ proc hash*[T](x: ptr[T]): Hash {.inline.} =
     assert cast[pointer](a[0].addr).hash == a[0].addr.hash
   hash(cast[pointer](x))
 
-when defined(nimEnableHashRef):
+when defined(nimPreviewHashRef) or defined(nimdoc):
   proc hash*[T](x: ref[T]): Hash {.inline.} =
     ## Efficient `hash` overload.
-    runnableExamples:
+    ## 
+    ## .. important:: Use `-d:nimPreviewHashRef` to
+    ##    enable hashing `ref`s. It is expected that this behavior
+    ##    becomes the new default in upcoming versions.
+    runnableExamples("-d:nimPreviewHashRef"):
       type A = ref object
         x: int
       let a = A(x: 3)
@@ -247,7 +255,7 @@ when defined(nimEnableHashRef):
       assert ha != A(x: 3).hash # A(x: 3) is a different ref object from `a`.
       a.x = 4
       assert ha == a.hash # the hash only depends on the address
-    runnableExamples:
+    runnableExamples("-d:nimPreviewHashRef"):
       # you can overload `hash` if you want to customize semantics
       type A[T] = ref object
         x, y: T

tests/collections/ttables.nim

@@ -8,7 +8,6 @@ And we get here
 '''
 joinable: false
 targets: "c cpp js"
-matrix: "-d:nimEnableHashRef"
 """
 
 # xxx wrap in a template to test in VM, see https://github.com/timotheecour/Nim/issues/534#issuecomment-769565033

tests/config.nims

@@ -39,3 +39,4 @@ switch("define", "nimExperimentalLinenoiseExtra")
 switch("define", "nimPreviewFloatRoundtrip")
 switch("define", "nimPreviewDotLikeOps")
 switch("define", "nimPreviewJsonutilsHoleyEnum")
+switch("define", "nimPreviewHashRef")

tests/stdlib/thashes.nim

@@ -1,6 +1,5 @@
 discard """
   targets: "c cpp js"
-  matrix: "-d:nimEnableHashRef"
 """
 
 import std/hashes