document general use of `_`, error message, fixes (#21584)

* document general use of `_`, error message, fixes

fixes #20687, fixes #21435

Documentation and changelog updated to clarify new universal behavior
of `_`. Also new error message for attempting to use `_`, new tests,
and fixes with overloadable symbols and
implicit generics.

* add test for #21435

5 files changed, 23 insertions, 4 deletions

diff --git a/tests/stmt/tforloop_tuple_multiple_underscore.nim b/tests/stmt/tforloop_tuple_multiple_underscore.nim
index 2afdb0b77..96804df18 100644
--- a/tests/stmt/tforloop_tuple_multiple_underscore.nim
+++ b/tests/stmt/tforloop_tuple_multiple_underscore.nim
@@ -1,5 +1,5 @@
 discard """
-  errormsg: "undeclared identifier: '_'"
+  errormsg: "the special identifier '_' is ignored in declarations and cannot be used"
 """
 
 iterator iter(): (int, int, int) =
@@ -7,4 +7,4 @@ iterator iter(): (int, int, int) =
 
 
 for (_, i, _) in iter():
-  echo _
\ No newline at end of file
+  echo _
diff --git a/tests/stmt/tforloop_tuple_underscore.nim b/tests/stmt/tforloop_tuple_underscore.nim
index 8cbb0fc10..eda42d527 100644
--- a/tests/stmt/tforloop_tuple_underscore.nim
+++ b/tests/stmt/tforloop_tuple_underscore.nim
@@ -1,5 +1,5 @@
 discard """
-  errormsg: "undeclared identifier: '_'"
+  errormsg: "the special identifier '_' is ignored in declarations and cannot be used"
 """
 
 iterator iter(): (int, int) =
diff --git a/tests/stmt/tforloop_underscore.nim b/tests/stmt/tforloop_underscore.nim
index c5b49da77..ce1c86386 100644
--- a/tests/stmt/tforloop_underscore.nim
+++ b/tests/stmt/tforloop_underscore.nim
@@ -1,5 +1,5 @@
 discard """
-  errormsg: "undeclared identifier: '_'"
+  errormsg: "the special identifier '_' is ignored in declarations and cannot be used"
 """
 
 for _ in ["a"]:
diff --git a/tests/stmt/tgenericsunderscore.nim b/tests/stmt/tgenericsunderscore.nim
new file mode 100644
index 000000000..be2b8ec78
--- /dev/null
+++ b/tests/stmt/tgenericsunderscore.nim
@@ -0,0 +1,4 @@
+# issue #21435
+
+proc foo[_](x: typedesc[_]): string = "BAR" #[tt.Error
+                        ^ the special identifier '_' is ignored in declarations and cannot be used]#
diff --git a/tests/stmt/tmiscunderscore.nim b/tests/stmt/tmiscunderscore.nim
new file mode 100644
index 000000000..c4bae1c3d
--- /dev/null
+++ b/tests/stmt/tmiscunderscore.nim
@@ -0,0 +1,15 @@
+import std/assertions
+
+block:
+  proc _() = echo "one"
+  doAssert not compiles(_())
+  proc _() = echo "two"
+  doAssert not compiles(_())
+
+block:
+  type _ = int
+  doAssert not (compiles do:
+    let x: _ = 3)
+  type _ = float
+  doAssert not (compiles do:
+    let x: _ = 3)