Change docs as suggested in SIP meeting

Author: odersky

docs/docs/reference/contextual/extension-methods.md

@@ -166,8 +166,7 @@ only be used for its extension methods.
 ### Collective Extensions
 
 Sometimes, one wants to define several extension methods that share the same
-left-hand parameter type. In this case one can "pull out" the common parameters
-into the extension instance itself. Examples:
+left-hand parameter type. In this case one can "pull out" the common parameters into the extension instance itself. Examples:
 ```scala
 extension stringOps on (ss: Seq[String]) {
   def longestStrings: Seq[String] = {
@@ -186,6 +185,11 @@ extension on [T](xs: List[T])(using Ordering[T]) {
   def largest(n: Int) = xs.sorted.takeRight(n)
 }
 ```
+**Note**: If a collective extension defines type parameters in its prefix
+(as the `listOps` extension above does), the extension methods themselves are not
+allowed to have additional type parameters. This restriction might be lifted in the
+future once we support multiple type parameter clauses in a method.
+
 Collective extensions like these are a shorthand for extension instances where
 the parameters following the `on` are repeated for each implemented method.
 For instance, the collective extensions above expand to the following extension instances:
@@ -217,6 +221,18 @@ parameter `ss`. The usage is made explicit when translating the method:
 def (ss: Seq[String]).longestString: String =
   ss.longestStrings.head
 ```
+By contrast, the meaning of `this` in a collective extension is as usual
+a reference to the enclosing object (i.e. the one implementing the extension methods).
+It's not a reference to the shared parameter. So this means that the following
+implementation of `longestString` would be illegal:
+```scala
+def longestString: String = this.longestStrings.head   // error: missing parameter
+```
+But the following version would again be correct, since it calls the `longestString`
+method as a regular non-extension method, passing the prefix parameter `ss` as a regular parameter:
+```scala
+def longestString: String = this.longestStrings(ss).head
+```
 
 ### Syntax
 

docs/docs/reference/contextual/given-imports.md

@@ -100,7 +100,7 @@ The following modifications avoid this hurdle to migration.
 
 These rules mean that library users can use `given _` selectors to access old-style implicits in Scala 3.0,
 and will be gently nudged and then forced to do so in later versions. Libraries can then switch to
-representation clauses once their user base has migrated.
+given instances once their user base has migrated.
 
 ### Syntax
 

docs/docs/reference/contextual/givens.md

@@ -48,6 +48,17 @@ given [T](using Ord[T]) as Ord[List[T]] { ... }
 If the name of a given is missing, the compiler will synthesize a name from
 the implemented type(s).
 
+**Note** The name synthesized by the compiler is chosen to be readable and reasonably concise. For instance, the two instances above would get the names:
+```scala
+given_Ord_Int
+given_Ord_List_T
+```
+The precise rules for synthesizing names are found in [./relationship-implicit.html]. These rules do not guarantee absence of name conflicts between
+given instances of types that are "too similar". To avoid conflicts one can
+use named instances.
+
+**Note** To ensure robust binary compatibility, publicly available libraries should prefer named instances.
+
 ## Alias Givens
 
 An alias can be used to define a given instance that is equal to some expression. E.g.:

tests/new/test.scala

@@ -1,3 +1 @@
-trait T {
-  object O
-}
+inline def foo = 1