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

1 files changed, 26 insertions, 10 deletions

diff --git a/changelogs/changelog_2_0_0.md b/changelogs/changelog_2_0_0.md
index 19d97b769..a82ce149b 100644
--- a/changelogs/changelog_2_0_0.md
+++ b/changelogs/changelog_2_0_0.md
@@ -135,26 +135,42 @@
 
 - The experimental strictFuncs feature now disallows a store to the heap via a `ref` or `ptr` indirection.
 
-- Underscores (`_`) as routine parameters are now ignored and cannot be used in the routine body.
-  The following code now does not compile:
+- The underscore identifier (`_`) is now generally not added to scope when
+  used as the name of a definition. While this was already the case for
+  variables, it is now also the case for routine parameters, generic
+  parameters, routine declarations, type declarations, etc. This means that the following code now does not compile:
 
   ```nim
   proc foo(_: int): int = _ + 1
   echo foo(1)
+
+  proc foo[_](t: typedesc[_]): seq[_] = @[default(_)]
+  echo foo[int]()
+
+  proc _() = echo "_"
+  _()
+
+  type _ = int
+  let x: _ = 3
   ```
 
-  Instead, the following code now compiles:
+  Whereas the following code now compiles:
 
   ```nim
   proc foo(_, _: int): int = 123
   echo foo(1, 2)
-  ```
-- Underscores (`_`) as generic parameters are not supported and cannot be used.
-  Generics that use `_` as parameters will no longer compile requires you to replace `_` with something else:
-  
-  ```nim
-  proc foo[_](t: typedesc[_]): string = "BAR" # Can not compile
-  proc foo[T](t: typedesc[T]): string = "BAR" # Can compile
+
+  proc foo[_, _](): int = 123
+  echo foo[int, bool]()
+
+  proc foo[T, U](_: typedesc[T], _: typedesc[U]): (T, U) = (default(T), default(U))
+  echo foo(int, bool)
+
+  proc _() = echo "one"
+  proc _() = echo "two"
+
+  type _ = int
+  type _ = float
   ```
 
 - - Added the `--legacy:verboseTypeMismatch` switch to get legacy type mismatch error messages.