Merge pull request #10288 from ShapelessCat/fix-docs

Author: smarter

docs/docs/reference/other-new-features/safe-initialization.md

@@ -29,7 +29,7 @@ The checker will report:
 
 ``` scala
 -- Warning: tests/init/neg/AbstractFile.scala:7:4 ------------------------------
-7 |	val localFile: String = url.hashCode + ".tmp"  // error
+7 |	val localFile: String = s"${url.##}.tmp"  // error: usage of `localFile` before it's initialized
   |	    ^
   |    Access non-initialized field value localFile. Calling trace:
   |     -> val extension: String = name.substring(4)	[ AbstractFile.scala:3 ]
@@ -183,7 +183,6 @@ are transitively initialized, so is the result.
 
 With the established principles and design goals, following rules are imposed:
 
-
 1. In an assignment `o.x = e`, the expression `e` may only point to transitively initialized objects.
 
    This is how monotonicity is enforced in the system. Note that in an

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

@@ -4,17 +4,21 @@ 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:
-```
+
+```java
 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
@@ -38,58 +42,69 @@ The `@targetName` annotation has no bearing on Scala usages. Any application of
 
 `@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.
+- 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.
 
 However, `@targetName` annotations are not allowed to break overriding relationships
 between two definitions that have otherwise the same names and types. So the following would be in error:
+
 ```scala
 import annotation.targetName
 class A:
   def f(): Int = 1
 class B extends A:
-  targetName("g") def f(): Int = 2
+  @targetName("g") def f(): Int = 2
 ```
+
 The compiler reports here:
+
 ```
 -- Error: test.scala:6:23 ------------------------------------------------------
 6 |  @targetName("g") def f(): Int = 2
   |                       ^
   |error overriding method f in class A of type (): Int;
   |  method f of type (): Int should not have a @targetName annotation since the overridden member hasn't one either
 ```
+
 The relevant overriding rules can be summarized as follows:
 
- - Two members can override each other if their names and signatures are the same,
-   and they either have the same erased names or the same types.
- - If two members override, then both their erased names and their types must be the same.
+- Two members can override each other if their names and signatures are the same,
+  and they either have the same erased names or the same types.
+- If two members override, then both their erased names and their types must be the same.
 
 As usual, any overriding relationship in the generated code must also
 be present in the original code. So the following example would also be in error:
+
 ```scala
 import annotation.targetName
 class A:
   def f(): Int = 1
 class B extends A:
-  targetName("f") def g(): Int = 2
+  @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:

tests/init/neg/AbstractFile.scala

@@ -4,6 +4,6 @@ abstract class AbstractFile {
 }
 
 class RemoteFile(url: String) extends AbstractFile {
-	val localFile: String = url.hashCode + ".tmp"  // error
+	val localFile: String = s"${url.##}.tmp"  // error: usage of `localFile` before it's initialized
 	def name: String = localFile
 }