Incorporate feedback from @lrytz, @janekdb and @dwijnand.

Author: DarkDimius

Diff for: sips/pending/_posts/2016-01-01-static-members.md renamed to sips/pending/_posts/2016-01-11-static-members.md

@@ -4,9 +4,9 @@ title: SIP 25 - @static fields and methods in Scala objects(SI-4581)
 disqus: true
 ---
 
-__Dmitry Petrashko and Sébastien Doeraene__
+__Dmitry Petrashko, Sébastien Doeraene and Martin Odersky__
 
-__first submitted TODO 2016__
+__first submitted 11 January 2016__
 
 ## Motivation ##
 
@@ -18,18 +18,19 @@ Some JVM and JavaScript frameworks require classes to have specific static field
 
 For example, classes extending `android.os.Parcelable` are required to have a static field named `CREATOR` of type `android.os.Parcelable$Creator`.
 
-Another example is using an [`AtomicReferenceFieldUpdater`](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.html).
+Another example is using an [`AtomicReferenceFieldUpdater`](http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.html).
 
 On the JavaScript side, one example is [Relay Route Definitions](https://facebook.github.io/relay/docs/guides-routes.html), whose subclasses must define static fields such as `queries`.
 Static methods and fields for JavaScript classes are one of the very few things (if not the only thing) that Scala.js "cannot do" at the moment, at least not declaratively.
 
 ## Overview ##
 
-In order for method or field to be considered static it needs to be defined in an `object` and annotated `@static`.
+In order for a method or field to be considered static it needs to be defined in an `object` and annotated `@static`.
 There is no special syntax proposed to access these members, they are accessed as if they were a member of defining objects with all appropriate access requirements for accessing them.
 
 For example:
 
+```scala
 {% highlight scala %}
 class Foo
 
@@ -41,10 +42,12 @@ object Foo {
 println(Foo.x)
 println(Foo.bar(12))
 {% endhighlight %}
+```
 
-Intuively, the presence of the `@static` annotation ensures that a field/method is declared as a static member of the companion class.
+Intuitively, the presence of the `@static` annotation ensures that a field/method is declared as a static member of the companion class.
 For the JVM, the above would therefore look to other Java code as if it had been declared with the following Java code:
 
+```java
 {% highlight java %}
 class Foo {
   public static int x = 5;
@@ -53,10 +56,12 @@ class Foo {
   }
 }
 {% endhighlight %}
+```
 
 In Scala.js, the `@static` annotation has no semantic effect in Scala objects, as they are not visible from JavaScript anyway (it could be used for optimizations).
 It has a semantic effect on Scala.js-defined JS classes, for example:
 
+```scala
 {% highlight scala %}
 @ScalaJSDefined
 class Foo extends js.Object
@@ -67,9 +72,11 @@ object Foo extends js.Object {
   @static def bar(y: Int): Int = x + y
 }
 {% endhighlight %}
+```
 
 would look to JavaScript code as if it had been declared with the following JavaScript code:
 
+```javascript
 {% highlight javascript %}
 class Foo extends Object {
   static bar(y) {
@@ -78,22 +85,42 @@ class Foo extends Object {
 }
 Foo.x = 5; // in ES6, there is no declarative syntax for static fields yet
 {% endhighlight %}
+```
+
+## Comparison with mirror classes ##
+
+Scalac currently generates static forwarders for fields and methods in top-level objects:
+
+```scala
+{% highlight scala %}
+object O {
+  val d = 1 
+  object I {
+    val f = 1
+  }
+}
+{% endhighlight %}
+```
+
+Under the proposed scheme users will be able to opt-in to have the field `f` defined in the inner object `I` emited as a static field. 
+In case `O.d` is annotated with `@static` the field will be crated as a static field `d` in `class O`.
+If not annotated, it will be created in the companion module with a static forwarder `d` in `class O`.
 
 ## Restrictions ##
 
-The following rules ensure that method can be correctly compiled into static member on both JVM and JavaScript:
+The following rules ensure that methods can be correctly compiled into static members on both JVM and JavaScript:
 
 1. Only objects can have members annotated with `@static`
 
 2. The fields annotated with `@static` should preceed any non-`@static` fields. This ensures that we do not introduce surprises for users in initialization order.
 
-3. The right hand side of a method or field annotated with `@static` can only refer to members of globally accessible objects and `@static` members. In particular, for non-static objects `this` is not accesible. `super` is never accessible.
+3. The right hand side of a method or field annotated with `@static` can only refer to top-level classes, members of globally accessible objects and `@static` members. In particular, for non-static objects `this` is not accesible. `super` is never accessible.
 
 4. If a member `foo` of an `object C` is annotated with `@static`, the companion class `C` is not allowed to define term members with name `foo`. 
 
 5. If a member `foo` of an `object C` is annotated with `@static`, the companion class `C` is not allowed to inherit classes that define a term member with name `foo`.
 
-6. Only @static methods and vals are supported in companions of traits. Java8 supports those, but not vars, and JavaScript does not have interfaces at all.
+6. Only `@static` methods and vals are supported in companions of traits. Java8 supports those, but not vars, and JavaScript does not have interfaces at all.
 
 ## Compilation scheme ##
 No modificaiton of the typer is planned. The current proposed scheme piggybacks on already existing scoping restrictions in the typer, thus requiring `@static` methods to be defined in `objects`.
@@ -103,14 +130,14 @@ If implemented in the dotty code base, the following modifications would be need
  - extend `LambdaLift` to trigger an error if a method annotated with `@static` method cannot be lifted to the top level scope;
  - extend `GenBCode` to emit static fields and methods in companion classes and forwarders to them in companion modules.
 
-## Overriding&Hiding ##
+## Overriding & Hiding ##
 Java allows classes to define static methods with the same name and signature as a static method of a superclass. In order to define the semantics of such cases, the Java Specification introduces the notion of [hiding](http://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4.8.2).
 
 This is required because in Java calling a `static` method on a class instance is supported.
 This proposal does not need to introduce this notion as we do not support such calls.
 
 ## Comparison with [@lrytz's proposal](https://gist.github.com/lrytz/80f3141de8240f9629da) ##
-Lucas Rytz has proposed a similar SIP, but his SIP requires changes to the typer to ensure that `@static` fields do not capture `this`, as in his proposal `@static` fields are defined in the class, rather than its companion object.
+Lukas Rytz has proposed a similar SIP, but his SIP requires changes to the typer to ensure that `@static` fields do not capture `this`, as in his proposal `@static` fields are defined in the class, rather than its companion object.
 It also does not address the question of `@static` members in inner objects and inheritance/hiding of those methods in subclasses.
 
 ## Open questions ##