SI-6879 improves Context.freshName

Instead of per-compilation unit unique counters, the freshName API now
uses a per-Global counter. Fresh names now also contain dollars to exclude
clashes with supported user-defined names (the ones without dollar signs).

This doesn’t fix the bug, because per-Global counters get created anew
every time a new Global is instantiated, and that provides some potential
for name clashes even for def macros, but at least it completely excludes
clashes in typical situations.

1 files changed, 29 insertions, 11 deletions

diff --git a/src/reflect/scala/reflect/macros/Names.scala b/src/reflect/scala/reflect/macros/Names.scala
index af60dffbfc..4f3448e1ed 100644
--- a/src/reflect/scala/reflect/macros/Names.scala
+++ b/src/reflect/scala/reflect/macros/Names.scala
@@ -6,33 +6,51 @@ package macros
  * <span class="badge badge-red" style="float: right;">EXPERIMENTAL</span>
  *
  *  A slice of [[scala.reflect.macros.blackbox.Context the Scala macros context]] that
- *  provides functions that generate unique names.
+ *  provides functions that generate fresh names.
+ *
+ *  In the current implementation, fresh names are more or less unique in the sense that
+ *  within the same compilation run they are guaranteed not to clash with:
+ *    1) Results of past and future invocations of functions of `freshName` family
+ *    2) User-defined or macro-generated names that don't contain dollar symbols
+ *    3) Macro-generated names that are created by concatenating names from the first, second and third categories
+ *
+ *  Uniqueness of fresh names across compilation runs is not guaranteed, but that's something
+ *  that we would like to improve upon in future releases. See [[https://issues.scala-lang.org/browse/SI-6879]] for more information.
+ *
+ *  @define freshNameNoParams
+ *  Creates a string that represents a more or less unique name.
+ *  Consult [[scala.reflect.macros.Names]] for more information on uniqueness of such names.
+ *
+ *  @define freshNameStringParam
+ *  Creates a string that represents a more or less unique name having a given prefix.
+ *  Consult [[scala.reflect.macros.Names]] for more information on uniqueness of such names.
+ *
+ *  @define freshNameNameParam
+ *  Creates a more or less unique name having a given name as a prefix and
+ *  having the same flavor (term name or type name) as the given name.
+ *  Consult [[scala.reflect.macros.Names]] for more information on uniqueness of such names.
  */
 trait Names {
   self: blackbox.Context =>
 
-  /** Creates a unique string. */
+  /** $freshNameNoParams */
   @deprecated("Use freshName instead", "2.11.0")
   def fresh(): String
 
-  /** Creates a unique string having a given prefix. */
+  /** $freshNameStringParam */
   @deprecated("Use freshName instead", "2.11.0")
   def fresh(name: String): String
 
-  /** Creates a unique name having a given name as a prefix and
-   *  having the same flavor (term name or type name) as the given name.
-   */
+  /** $freshNameNameParam */
   @deprecated("Use freshName instead", "2.11.0")
   def fresh[NameType <: Name](name: NameType): NameType
 
-  /** Creates a unique string. */
+  /** $freshNameNoParams */
   def freshName(): String
 
-  /** Creates a unique string having a given prefix. */
+  /** $freshNameStringParam */
   def freshName(name: String): String
 
-  /** Creates a unique name having a given name as a prefix and
-   *  having the same flavor (term name or type name) as the given name.
-   */
+  /** $freshNameNameParam */
   def freshName[NameType <: Name](name: NameType): NameType
 }