Update doc page

Author: odersky

docs/docs/reference/other-new-features/creator-applications.md

@@ -1,10 +1,11 @@
 ---
 layout: doc-page
-title: "Creator Applications"
+title: "Universal Apply Methods"
 ---
 
-Creator applications allow using simple function call syntax to create instances
-of a class, even if there is no apply method implemented. Example:
+Scala case classes generate apply methods, so that values of case classes can be created using simple function application, without needing to write `new`.
+
+Scala 3 generalizes this scheme to all concrete classes. Example:
 ```scala
 class StringBuilder(s: String) {
    def this() = this("")
@@ -13,31 +14,33 @@ class StringBuilder(s: String) {
 StringBuilder("abc")  // same as new StringBuilder("abc")
 StringBuilder()       // same as new StringBuilder()
 ```
-Creator applications generalize a functionality provided so far only for case classes, but the mechanism how this is achieved is different. Instead of generating an apply method, the compiler adds a new possible interpretation to a function call `f(args)`. The previous rules are:
-
-Given a function call `f(args)`,
+This works since a companion object with two apply methods
+is generated together with the class. The object looks like this:
+```scala
+object StringBuilder {
+  inline def apply(s: String): StringBuilder = new StringBuilder(s)
+  inline def apply(): StringBuilder = new StringBuilder()
+}
+```
+The synthetic object `StringBuilder` and its `apply` methods are called _constructor proxies_.
+Constructor proxies are generated even for Java classes and classes coming from Scala 2.
+The precise rules are as follows:
 
- - if `f` is a method applicable to `args`, typecheck `f(args)` unchanged,
- - otherwise, if `f` has an `apply` method applicable to `args` as a member, continue with `f.apply(args)`,
- - otherwise, if `f` is of the form `p.m` and there is an implicit conversion `c` applicable to `p` so that `c(p).m` is applicable to `args`, continue with `c(p).m(args)`
+ 1. A constructor proxy companion object `object C` is created for a concrete class `C`, provided the class does not have already a companion, and there is also no other value or method named `C` defined or inherited in the scope where `C` is defined.
 
-There's now a fourth rule following these rules:
+ 2. Constructor proxy `apply` methods are generated for a concrete class provided
 
- - otherwise, if `f` is syntactically a stable identifier, and `new f` where `f` is interpreted as a type identifier is applicable to `args`, continue with `new f(args)`.
+   - the class has a companion object (which might have been generated in step 1), and
+   - that companion object does not already define a member named `apply`.
 
- Analogously, the possible interpretations of a function call with type arguments `f[targs]` are augmented with the following interpretation as a final fallback:
+   Each generated `apply` method forwards to one constructor of the class. It has the
+   same type and value parameters as the constructor.
 
- - if `f` is syntactically a stable identifier, and `new f[targs]` where `f` is interpreted as a type identifier is well-typed, continue with `new f[targs]`.
+Constructor proxy companions cannot be used as values by themselves. A proxy companion object must be selected with `apply` (or be applied to arguments, in which case the `apply` is implicitly inserted).
 
+Constructor proxies are also not allowed to shadow normal definitions. That is,
+if an identifier resolves to a constructor proxy, and the same identifier is also
+defined or imported in some other scope, an ambiguity is reported.
 ### Motivation
 
 Leaving out `new` hides an implementation detail and makes code more pleasant to read. Even though it requires a new rule, it will likely increase the perceived regularity of the language, since case classes already provide function call creation syntax (and are often defined for this reason alone).
-
-### Discussion
-
-An alternative design would auto-generate `apply` methods for normal classes, in the same way it is done now for case classes. This design was tried but abandoned since it
-caused numerous problems, including
-
- - overloading ambiguities
- - overriding errors
- - shadowing of user-defined `apply` methods by more specific auto-generated ones.

docs/sidebar.yml

@@ -93,7 +93,7 @@ sidebar:
               url: docs/reference/other-new-features/trait-parameters.html
             - title: Transparent Traits
               url: docs/reference/other-new-features/transparent-traits.html
-            - title: Creator Applications
+            - title: Universal Applies
               url: docs/reference/other-new-features/creator-applications.html
             - title: Export Clauses
               url: docs/reference/other-new-features/export.html