Update reference pages

Author: odersky

docs/docs/reference/changed-features/operators.md

@@ -3,60 +3,17 @@ layout: doc-page
 title: Rules for Operators
 ---
 
-The rules for infix operators have changed. There are two annotations that regulate operators: `infix` and `alpha`.
-Furthermore, a syntax change allows infix operators to be written on the left in a multi-line expression.
+The rules for infix operators have changed in some parts:
 
-## The @alpha Annotation
-
-An `@alpha` annotation on a method definition defines an alternate name for the implementation of that method: Example:
-```scala
-import scala.annotation.alpha
-
-object VecOps {
-  @alpha("append") def (xs: Vec[T]) ++= [T] (ys: Vec[T]): Vec[T] = ...
-}
-```
-Here, the `++=` operation is implemented (in Byte code or native code) under the name `append`. The implementation name affects the code that is generated, and is the name under which code from other languages can call the method. For instance, `++=` could be invoked from Java like this:
-```
-VecOps.append(vec1, vec2)
-```
-The `@alpha` annotation has no bearing on Scala usages. Any application of that method in Scala has to use `++=`, not `append`.
-
-### Motivation
-
-The `@alpha` annotation serves a dual purpose:
-
- - It helps interoperability between Scala and other languages.
- - It serves as a documentation tool by providing an alternative regular name
-   as an alias of a symbolic operator.
-
-### Details
-
- 1. `@alpha` is defined in package `scala.annotation`. It takes a single argument
-    of type `String`. That string is called the _external name_ of the definition
-    that's annotated.
-
- 2. An `@alpha` annotation can be given for all kinds of definitions.
-
- 3. The name given in an `@alpha` annotation must be a legal name
-    for the defined entities on the host platform.
-
- 4. Definitions with symbolic names should have an `@alpha` annotation. Lack of such
-    an annotation will raise a deprecation warning.
-
- 5. Definitions with names in backticks that are not legal host platform names
-    should have an `@alpha` annotation. Lack of such an annotation will raise a deprecation warning.
-
- 6. `@alpha` annotations must agree: If two definitions are members of an object or class with the same name and matching types, then either none of them has an `@alpha` annotation, or both have `@alpha` annotations with the same name.
-
- 7. There must be a one-to-one relationship between external and internal names:
- If two definitions are members of an object or class with matching types and both have `@alpha` annotations with the same external name, then their internal method names must also be the same.
+First, an alphanumeric method can be used as an infix operator only if its definition carries an `@infix` annotation. Second, it is recommended (but not enforced) to
+augment definitions of symbolic operators with `@targetName` annotations. Finally,
+a syntax change allows infix operators to be written on the left in a multi-line expression.
 
 ## The @infix Annotation
 
 An `@infix` annotation on a method definition allows using the method as an infix operation. Example:
 ```scala
-import scala.annotation.alpha
+import scala.annotation.{infix, targetName}
 
 trait MultiSet[T] {
 
@@ -65,7 +22,7 @@ trait MultiSet[T] {
 
   def difference(other: MultiSet[T]): MultiSet[T]
 
-  @alpha("intersection")
+  @targetName("intersection")
   def *(other: MultiSet[T]): MultiSet[T]
 }
 
@@ -133,6 +90,19 @@ The purpose of the `@infix` annotation is to achieve consistency across a code b
  5. To smooth migration to Scala 3.0, alphanumeric operators will only be deprecated from Scala 3.1 onwards,
 or if the `-source 3.1` option is given in Dotty/Scala 3.
 
+## The @targetName Annotation
+
+It is recommended that definitions of symbolic operators carry a [@targetName annotation](../other-new-features/targetName.html) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
+
+ - It helps interoperability between Scala and other languages. One can call
+   a Scala-defined symbolic operator from another language using its target name,
+   which avoids having to remember the low-level encoding of the symbolic name.
+ - It helps legibility of stacktraces and other runtime diagnostics, where the
+   user-defined alphanumeric name will be shown instead of the low-level encoding.
+ - It serves as a documentation tool by providing an alternative regular name
+   as an alias of a symbolic operator. This makes the definition also easier
+   to find in a search.
+
 ## Syntax Change
 
 Infix operators can now appear at the start of lines in a multi-line expression. Examples:

docs/docs/reference/other-new-features/targetName.md

@@ -0,0 +1,79 @@
+---
+layout: doc-page
+title: The @targetName annotation
+---
+
+A `@targetName` annotation on a definition defines an alternate name for the implementation of that definition: Example:
+```scala
+import scala.annotation.targetName
+
+object VecOps {
+  @targetName("append") def (xs: Vec[T]) ++= [T] (ys: Vec[T]): Vec[T] = ...
+}
+```
+Here, the `++=` operation is implemented (in Byte code or native code) under the name `append`. The implementation name affects the code that is generated, and is the name under which code from other languages can call the method. For instance, `++=` could be invoked from Java like this:
+```
+VecOps.append(vec1, vec2)
+```
+The `@targetName` annotation has no bearing on Scala usages. Any application of that method in Scala has to use `++=`, not `append`.
+
+### Details
+
+ 1. `@targetName` is defined in package `scala.annotation`. It takes a single argument
+    of type `String`. That string is called the _external name_ of the definition
+    that's annotated.
+
+ 2. A `@targetName` annotation can be given for all kinds of definitions.
+
+ 3. The name given in a `@targetName` annotation must be a legal name
+    for the defined entities on the host platform.
+
+ 4. It is recommended that definitions with symbolic names have a `@targetName` annotation. This will establish an alternate name that is easier to search for and
+ will avoid cryptic encodings in runtime diagnostics.
+
+ 5. Definitions with names in backticks that are not legal host platform names
+    should also have a `@targetName` annotation.
+
+### Relationship with Overriding
+
+`@targetName` annotations are significant for matching two method definitions to decide whether they conflict or override each other. Two method definitions match if they have the same name, signature, and erased name. Here,
+
+ - The _signature_ of a definition consists of the names of the erased types of all (value-) parameters and the method's result type.
+ - The _erased name_ of a method definition is its target name if a `@targetName`
+   annotation is given and its defined name otherwise.
+
+This means that `@targetName` annotations can be used to disambiguate two method definitions that would otherwise clash. For instance.
+```scala
+def f(x: => String): Int = x.length
+def f(x: => Int): Int = x + 1  // error: double definition
+```
+The two definitions above clash since their erased parameter types are both `Function0`, which is the type of the translation of a by-name-parameter. Hence
+they have the same names and signatures. But we can avoid the clash by adding  a `@targetName` annotation to either method or to both of them. E.g.
+```scala
+@targetName("f_string")
+def f(x: => String): Int = x.length
+def f(x: => Int): Int = x + 1  // OK
+```
+This will produce methods `f_string` and `f` in the generated code.
+
+As usual, any overriding relationship in the generated code must also
+be present in the original code. So the following example would be in error:
+```scala
+import annotation.targetName
+class A:
+  def f(): Int = 1
+class B extends A:
+  targetName("f") def g(): Int = 2
+```
+Here, the original methods `g` and `f` do not override each other since they have
+different names. But once we switch to target names, there is a clash that is reported by the compiler:
+```
+-- [E120] Naming Error: test.scala:4:6 -----------------------------------------
+4 |class B extends A:
+  |      ^
+  |      Name clash between defined and inherited member:
+  |      def f(): Int in class A at line 3 and
+  |      def g(): Int in class B at line 5
+  |      have the same name and type after erasure.
+1 error found
+```

docs/docs/reference/overview.md

@@ -58,8 +58,8 @@ These constructs are restricted to make the language safer.
  - [Given Imports](contextual/given-imports.md): implicits now require a special form of import, to make the import clearly visible.
  - [Type Projection](dropped-features/type-projection.md): only classes can be used as prefix `C` of a type projection `C#A`. Type projection on abstract types is no longer supported since it is unsound.
  - [Multiversal Equality](contextual/multiversal-equality.md) implements an "opt-in" scheme to rule out nonsensical comparisons with `==` and `!=`.
- - [@infix and @alpha](changed-features/operators.md)
- make method application syntax uniform across code bases and require alphanumeric aliases for all symbolic names (proposed, not implemented).
+ - [@infix annotations](changed-features/operators.md)
+ make method application syntax uniform across code bases.
 
 Unrestricted implicit conversions continue to be available in Scala 3.0, but will be deprecated and removed later. Unrestricted versions of the other constructs in the list above are available only under `-source 3.0-migration`.
 
@@ -109,6 +109,7 @@ These are additions to the language that make it more powerful or pleasant to us
  - [Dependent Function Types](new-types/dependent-function-types.md) generalize dependent methods to dependent function values and types.
  - [Polymorphic Function Types](https://github.com/lampepfl/dotty/pull/4672) generalize polymorphic methods to dependent function values and types. _Current status_: There is a proposal, and a prototype implementation, but the implementation has not been finalized or merged yet.
  - [Kind Polymorphism](other-new-features/kind-polymorphism.md) allows the definition of operators working equally on types and type constructors.
+ - [@targetName Annotations](other-new-features/targetName.md) make it easier to interoperate with code written in other languages and give more flexibility for avoiding name clashes.
 
 ## Metaprogramming
 

docs/sidebar.yml

@@ -103,8 +103,10 @@ sidebar:
               url: docs/reference/other-new-features/kind-polymorphism.html
             - title: Tupled Function
               url: docs/reference/other-new-features/tupled-function.html
-            - title: threadUnsafe Annotation
+            - title: @threadUnsafe Annotation
               url: docs/reference/other-new-features/threadUnsafe-annotation.html
+            - title: @targetName Annotation
+              url: docs/reference/other-new-features/targetName.html
             - title: New Control Syntax
               url: docs/reference/other-new-features/control-syntax.html
             - title: Optional Braces

tests/neg/override-erasure-clash.check

@@ -0,0 +1,7 @@
+-- [E120] Naming Error: tests/neg/override-erasure-clash.scala:4:6 -----------------------------------------------------
+4 |class B extends A:   // error
+  |      ^
+  |      Name clash between defined and inherited member:
+  |      def f(): Int in class A at line 3 and
+  |      def g(): Int in class B at line 5
+  |      have the same name and type after erasure.

tests/neg/override-erasure-clash.scala

@@ -0,0 +1,6 @@
+import annotation.targetName
+class A:
+  def f(): Int = 1
+class B extends A:   // error
+  @targetName("f") def g(): Int = 2
+