Add link to collections API overview to scaladoc of collection classes (SI-5280) #30

joshmarcus · 2011-12-05T17:21:01Z

See https://issues.scala-lang.org/browse/SI-5280

Recently, on scala-debate, Martin Odersky wrote: "I think two of the things we need to do on the docs side is hide implementation details better in the ScalaDoc and put a link to the collections API overview

http://www.scala-lang.org/docu/files/collections-api/collections.html

into the scaladoc of each collection class."

I've implemented the second suggestion. For the classes that have their own pages in the collections API overview, I've added @see ("See also") links to their specific pages in the collections API overview. I used the existing @see from Array.scala as a model.

…ges of "The Scala 2.8 Collections API" overview.

joshmarcus · 2011-12-05T17:24:49Z

There is a formatting issue I need to fix. I will resubmit this request.

Protobuf support

``` cat sandbox/test.scala && qscalac -target:jvm-1.8 -Ybackend:GenASM sandbox/test.scala && (for c in 'T' 'T$' 'C'; do javap -c -classpath . $c; done) | cat -v; qscala Test trait T { def t(s: String) = 42 val v = 42 } class C extends T object Test { def main(args: Array[String]): Unit = { println(new C().t("")) } } Compiled from "test.scala" public interface T { public abstract void T$_setter_$v_$eq(int); public int t(java.lang.String); Code: 0: bipush 42 2: ireturn public abstract int v(); } Error: class not found: T$ Compiled from "test.scala" public class C implements T { public int v(); Code: 0: aload_0 1: getfield #15 // Field v:I 4: ireturn public void T$_setter_$v_$eq(int); Code: 0: aload_0 1: iload_1 2: putfield #15 // Field v:I 5: return public C(); Code: 0: aload_0 1: invokespecial #24 // Method java/lang/Object."<init>":()V 4: aload_0 5: invokestatic #30 // Method T$class.$init$:(LT;)V 8: return } 42 topic/indylambda-emit-indy /code/scala2 cat sandbox/test.scala && qscalac -target:jvm-1.8 -Ybackend:GenBCode sandbox/test.scala && (for c in 'T' 'T$' 'C'; do javap -c -classpath . $c; done) | cat -v; qscala Test trait T { def t(s: String) = 42 val v = 42 } class C extends T object Test { def main(args: Array[String]): Unit = { println(new C().t("")) } } Compiled from "test.scala" public interface T { public abstract void T$_setter_$v_$eq(int); public int t(java.lang.String); Code: 0: bipush 42 2: ireturn public abstract int v(); } Error: class not found: T$ Compiled from "test.scala" public class C implements T { public int v(); Code: 0: aload_0 1: getfield #15 // Field v:I 4: ireturn public void T$_setter_$v_$eq(int); Code: 0: aload_0 1: iload_1 2: putfield #15 // Field v:I 5: return public C(); Code: 0: aload_0 1: invokespecial #24 // Method java/lang/Object."<init>":()V 4: aload_0 5: invokestatic #30 // Method T$class.$init$:(LT;)V 8: return } 42 ```

See also: https://github.com/retronym/indy-structural ``` qscalac -target:jvm-1.8 -Ybackend:GenBCode sandbox/structural.scala && qscala Test && javap -v 'Test$' | cat -v warning: there was one feature warning; re-run with -feature for details one warning found QUACK! A QUICK! A Classfile /Users/jason/code/scala2/Test$.class { public static final Test$ MODULE$; descriptor: LTest$; flags: ACC_PUBLIC, ACC_STATIC, ACC_FINAL public void main(java.lang.String[]); descriptor: ([Ljava/lang/String;)V flags: ACC_PUBLIC Code: stack=4, locals=2, args_size=2 0: getstatic #19 // Field scala/Predef$.MODULE$:Lscala/Predef$; 3: aload_0 4: new #21 // class C 7: dup 8: invokespecial #22 // Method C."<init>":()V 11: invokevirtual #26 // Method duckduck:(Ljava/lang/Object;)Ljava/lang/String; 14: invokevirtual #30 // Method scala/Predef$.println:(Ljava/lang/Object;)V 17: getstatic #19 // Field scala/Predef$.MODULE$:Lscala/Predef$; 20: aload_0 21: new #32 // class D 24: dup 25: invokespecial #33 // Method D."<init>":()V 28: invokevirtual #26 // Method duckduck:(Ljava/lang/Object;)Ljava/lang/String; 31: invokevirtual #30 // Method scala/Predef$.println:(Ljava/lang/Object;)V 34: return public java.lang.String duckduck(java.lang.Object); descriptor: (Ljava/lang/Object;)Ljava/lang/String; flags: ACC_PUBLIC Code: stack=2, locals=2, args_size=2 0: aload_1 1: ldc #38 // String A 3: invokedynamic #49, 0 // InvokeDynamic #0:"dyn:callMethod:quack":(Ljava/lang/Object;Ljava/lang/String;)Ljava/lang/String; 8: checkcast #51 // class java/lang/String 11: areturn } BootstrapMethods: 0: #45 invokestatic jdk/internal/dynalink/DefaultBootstrapper.bootstrap:(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;)Ljava/lang/invoke/CallSite; Method arguments: ```

See also: https://github.com/retronym/indy-structural ``` // sandbox/structural.scala object Test { def main(args: Array[String]): Unit = { println(duckduck(new C)) println(duckduck(new D)) } def duckduck(a: { def quack(a: String): String }): String = { a.quack("A") } } class C { def quack(a: String) = "QUACK! " + a } class D { def quack(a: String) = "QUICK! " + a } ``` ``` qscalac -target:jvm-1.8 -Ybackend:GenBCode sandbox/structural.scala && qscala Test && javap -v 'Test$' | cat -v warning: there was one feature warning; re-run with -feature for details one warning found QUACK! A QUICK! A Classfile /Users/jason/code/scala2/Test$.class { public static final Test$ MODULE$; descriptor: LTest$; flags: ACC_PUBLIC, ACC_STATIC, ACC_FINAL public void main(java.lang.String[]); descriptor: ([Ljava/lang/String;)V flags: ACC_PUBLIC Code: stack=4, locals=2, args_size=2 0: getstatic #19 // Field scala/Predef$.MODULE$:Lscala/Predef$; 3: aload_0 4: new #21 // class C 7: dup 8: invokespecial #22 // Method C."<init>":()V 11: invokevirtual #26 // Method duckduck:(Ljava/lang/Object;)Ljava/lang/String; 14: invokevirtual #30 // Method scala/Predef$.println:(Ljava/lang/Object;)V 17: getstatic #19 // Field scala/Predef$.MODULE$:Lscala/Predef$; 20: aload_0 21: new #32 // class D 24: dup 25: invokespecial #33 // Method D."<init>":()V 28: invokevirtual #26 // Method duckduck:(Ljava/lang/Object;)Ljava/lang/String; 31: invokevirtual #30 // Method scala/Predef$.println:(Ljava/lang/Object;)V 34: return public java.lang.String duckduck(java.lang.Object); descriptor: (Ljava/lang/Object;)Ljava/lang/String; flags: ACC_PUBLIC Code: stack=2, locals=2, args_size=2 0: aload_1 1: ldc #38 // String A 3: invokedynamic #49, 0 // InvokeDynamic #0:"dyn:callMethod:quack":(Ljava/lang/Object;Ljava/lang/String;)Ljava/lang/String; 8: checkcast #51 // class java/lang/String 11: areturn } BootstrapMethods: 0: #45 invokestatic jdk/internal/dynalink/DefaultBootstrapper.bootstrap:(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;)Ljava/lang/invoke/CallSite; Method arguments: ```

And do the same for the specialized variants. Tested by a Java source file that uses lambda syntax to create instances of generic and specialized `Function{0,1}`. Here's how the interfaces look now: ``` % javap -c -classpath /tmp/function 'scala.Function1' Compiled from "Function1.scala" public interface scala.Function1<T1, R> { public abstract R apply(T1); public <A> scala.Function1<A, R> compose(scala.Function1<A, T1>); Code: 0: aload_0 1: aload_1 2: invokestatic #18 // Method scala/Function1$class.compose:(Lscala/Function1;Lscala/Function1;)Lscala/Function1; 5: areturn public <A> scala.Function1<T1, A> andThen(scala.Function1<R, A>); Code: 0: aload_0 1: aload_1 2: invokestatic #24 // Method scala/Function1$class.andThen:(Lscala/Function1;Lscala/Function1;)Lscala/Function1; 5: areturn public abstract java.lang.String toString(); public int apply$mcII$sp(int); Code: 0: aload_0 1: iload_1 2: invokestatic #110 // Method scala/Function1$class.apply$mcII$sp:(Lscala/Function1;I)I 5: ireturn public long apply$mcJI$sp(int); Code: 0: aload_0 1: iload_1 2: invokestatic #115 // Method scala/Function1$class.apply$mcJI$sp:(Lscala/Function1;I)J 5: lreturn ... } % javap -c -classpath /tmp/function 'scala.Function1$mcII$sp' Compiled from "Function1.scala" public interface scala.Function1$mcII$sp extends scala.Function1<java.lang.Object, java.lang.Object> { public java.lang.Object apply(java.lang.Object); Code: 0: aload_0 1: aload_1 2: invokestatic #16 // Method scala/runtime/BoxesRunTime.unboxToInt:(Ljava/lang/Object;)I 5: invokeinterface #19, 2 // InterfaceMethod apply:(I)I 10: invokestatic #23 // Method scala/runtime/BoxesRunTime.boxToInteger:(I)Ljava/lang/Integer; 13: areturn public abstract int apply$mcII$sp(int); public int apply(int); Code: 0: aload_0 1: iload_1 2: invokeinterface #30, 2 // InterfaceMethod apply$mcII$sp:(I)I 7: ireturn } ```

And do the same for the specialized variants. Tested by a Java source file that uses lambda syntax to create instances of generic and specialized `Function{0,1}`. Here's how the interfaces look now: ``` % javap -c -classpath /tmp/function 'scala.Function1' Compiled from "Function1.scala" public interface scala.Function1<T1, R> { public abstract R apply(T1); public <A> scala.Function1<A, R> compose(scala.Function1<A, T1>); Code: 0: aload_0 1: aload_1 2: invokestatic #18 // Method scala/Function1$class.compose:(Lscala/Function1;Lscala/Function1;)Lscala/Function1; 5: areturn public <A> scala.Function1<T1, A> andThen(scala.Function1<R, A>); Code: 0: aload_0 1: aload_1 2: invokestatic #24 // Method scala/Function1$class.andThen:(Lscala/Function1;Lscala/Function1;)Lscala/Function1; 5: areturn public abstract java.lang.String toString(); public int apply$mcII$sp(int); Code: 0: aload_0 1: iload_1 2: invokestatic scala#110 // Method scala/Function1$class.apply$mcII$sp:(Lscala/Function1;I)I 5: ireturn public long apply$mcJI$sp(int); Code: 0: aload_0 1: iload_1 2: invokestatic scala#115 // Method scala/Function1$class.apply$mcJI$sp:(Lscala/Function1;I)J 5: lreturn ... } % javap -c -classpath /tmp/function 'scala.Function1$mcII$sp' Compiled from "Function1.scala" public interface scala.Function1$mcII$sp extends scala.Function1<java.lang.Object, java.lang.Object> { public java.lang.Object apply(java.lang.Object); Code: 0: aload_0 1: aload_1 2: invokestatic #16 // Method scala/runtime/BoxesRunTime.unboxToInt:(Ljava/lang/Object;)I 5: invokeinterface #19, 2 // InterfaceMethod apply:(I)I 10: invokestatic #23 // Method scala/runtime/BoxesRunTime.boxToInteger:(I)Ljava/lang/Integer; 13: areturn public abstract int apply$mcII$sp(int); public int apply(int); Code: 0: aload_0 1: iload_1 2: invokeinterface scala#30, 2 // InterfaceMethod apply$mcII$sp:(I)I 7: ireturn } ```

Dmitry learned that we've been relying on a bug in the verifier that will be fixed in JDK 9 under the new classfile format. Assignment to a static final must occur lexically within the <clinit>. We were performing this assignment from the constructor of the module class. I'd like to move the assignment to <clinit> but that would change behaviour of "benign" cyclic references between modules. Example: ``` package p1; class CC { def foo = O.bar}; object O {new CC().foo; def bar = println(1)}; // Exiting paste mode, now interpreting. scala> p1.O 1 ``` We currently assign the MODULE$ field after the super class constructors are finished, but before the rest of the module constructor is called. ``` private p1.O$(); Code: 0: aload_0 1: invokespecial #30 // Method java/lang/Object."<init>":()V 4: aload_0 5: putstatic #32 // Field MODULE$:Lp1/O$; 8: new #34 // class p1/CC 11: dup 12: invokespecial #35 // Method p1/CC."<init>":()V 15: invokevirtual #38 // Method p1/CC.foo:()V 18: return ``` This commit removes the ACC_FINAL bit from the field. It actually wasn't behaving as final at all, precisely the issue that the stricter verifier now alerts us to. ``` scala> :paste -raw // Entering paste mode (ctrl-D to finish) package p1; object O // Exiting paste mode, now interpreting. scala> val O1 = p1.O O1: p1.O.type = p1.O$@ee7d9f1 scala> scala.reflect.ensureAccessible(p1.O.getClass.getDeclaredConstructor()).newInstance() res0: p1.O.type = p1.O$@64cee07 scala> O1 eq p1.O res1: Boolean = false ```

Dmitry learned that we've been relying on a bug in the verifier that will be fixed in JDK 9 under the new classfile format. Assignment to a static final must occur lexically within the <clinit>. We were performing this assignment from the constructor of the module class. I'd like to move the assignment to <clinit> but that would change behaviour of "benign" cyclic references between modules. Example: ``` package p1; class CC { def foo = O.bar}; object O {new CC().foo; def bar = println(1)}; // Exiting paste mode, now interpreting. scala> p1.O 1 ``` We currently assign the MODULE$ field after the super class constructors are finished, but before the rest of the module constructor is called. ``` private p1.O$(); Code: 0: aload_0 1: invokespecial #30 // Method java/lang/Object."<init>":()V 4: aload_0 5: putstatic #32 // Field MODULE$:Lp1/O$; 8: new #34 // class p1/CC 11: dup 12: invokespecial #35 // Method p1/CC."<init>":()V 15: invokevirtual #38 // Method p1/CC.foo:()V 18: return ``` This commit removes the ACC_FINAL bit from the field. It actually wasn't behaving as final at all, precisely the issue that the stricter verifier now alerts us to. ``` scala> :paste -raw // Entering paste mode (ctrl-D to finish) package p1; object O // Exiting paste mode, now interpreting. scala> val O1 = p1.O O1: p1.O.type = p1.O$@ee7d9f1 scala> scala.reflect.ensureAccessible(p1.O.getClass.getDeclaredConstructor()).newInstance() res0: p1.O.type = p1.O$@64cee07 scala> O1 eq p1.O res1: Boolean = false ``` Fixes scala/scala-dev#SD-194

Crashes in ASM or VerifyErrors used to occur when assigning an expression of type Nothing to an element of a primitive array. This commit adapts the RHS of the assignment to the element type to correct this. `adapt` contains logic to insert an `ATHROW` of the slot of type `Nothing$`, which makes everything line up. The subsequent array stores become dead code and are dropped later on in code gen, so the test case compiles to: public void foo0(double[]); Code: 0: bipush 42 2: istore_2 3: aload_1 4: iconst_0 5: aload_0 6: invokevirtual #30 // Method throwExpected:()Lscala/runtime/Nothing$; 9: athrow

Crashes in ASM or VerifyErrors used to occur when assigning an expression of type Nothing to an element of a primitive array. This commit adapts the RHS of the assignment to the element type to correct this. `adapt` contains logic to insert an `ATHROW` of the slot of type `Nothing$`, which makes everything line up. The subsequent array stores become dead code and are dropped later on in code gen, so the test case compiles to: public void foo0(double[]); Code: 0: bipush 42 2: istore_2 3: aload_1 4: iconst_0 5: aload_0 6: invokevirtual #30 // Method throwExpected:()Lscala/runtime/Nothing$; 9: athrow I found a similar bug in the emission of primitive unboxing and fixed that too.

Before: ``` scala> trait T { val foo = 24 }; class C extends T defined trait T defined class C scala> :javap -private -c C Compiled from "<console>" public class $line3.$read$$iw$$iw$C implements $line3.$read$$iw$$iw$T { private final int foo; public int foo(); Code: 0: aload_0 1: getfield #21 // Field foo:I 4: ireturn public void $line3$$read$$iw$$iw$T$_setter_$foo_$eq(int); Code: 0: aload_0 1: iload_1 2: putfield #21 // Field foo:I 5: return public $line3.$read$$iw$$iw$C(); Code: 0: aload_0 1: invokespecial #30 // Method java/lang/Object."<init>":()V 4: aload_0 5: invokestatic #34 // InterfaceMethod $line3/$read$$iw$$iw$T.$init$:(L$line3/$read$$iw$$iw$T;)V 8: return } ``` The assignment to the final field `foo` has always contravened the JVM spec, and this rule is enforced for any classfiles of format 53 and higher. After this patch: ``` scala> trait T { val foo = 24 }; class C extends T defined trait T defined class C scala> :javap -private -c C Compiled from "<console>" public class $line3.$read$$iw$$iw$C implements $line3.$read$$iw$$iw$T { private int foo; public int foo(); Code: 0: aload_0 1: getfield #21 // Field foo:I 4: ireturn public void $line3$$read$$iw$$iw$T$_setter_$foo_$eq(int); Code: 0: aload_0 1: iload_1 2: putfield #21 // Field foo:I 5: return public $line3.$read$$iw$$iw$C(); Code: 0: aload_0 1: invokespecial #30 // Method java/lang/Object."<init>":()V 4: aload_0 5: invokestatic #34 // InterfaceMethod $line3/$read$$iw$$iw$T.$init$:(L$line3/$read$$iw$$iw$T;)V 8: getstatic #40 // Field scala/runtime/ScalaRunTime$.MODULE$:Lscala/runtime/ScalaRunTime$; 11: invokevirtual #43 // Method scala/runtime/ScalaRunTime$.releaseFence:()V 14: return } ```

fix scala#27: Add tasty-ci

Enhanced scaladoc of collection classes with links to the relevant pa…

6e90a1f

…ges of "The Scala 2.8 Collections API" overview.

joshmarcus closed this Dec 5, 2011

gkossakowski added a commit to gkossakowski/scala that referenced this pull request Jan 11, 2012

Merge pull request scala#30 from gkossakowski/protobuf

2a2029c

Protobuf support

retronym mentioned this pull request Nov 18, 2016

SI-10069 Fix code gen errors with array updates, Nothing #5543

Merged

scabug mentioned this pull request Apr 7, 2017

Scaladoc: @deprecated annotation should show 'since' attribute scala/bug#4801

Closed

bishabosha added a commit to bishabosha/scala that referenced this pull request Jan 28, 2020

Merge pull request scala#30 from scalacenter/tasty/ci

13353a3

fix scala#27: Add tasty-ci

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add link to collections API overview to scaladoc of collection classes (SI-5280) #30

Add link to collections API overview to scaladoc of collection classes (SI-5280) #30

joshmarcus commented Dec 5, 2011

joshmarcus commented Dec 5, 2011

Add link to collections API overview to scaladoc of collection classes (SI-5280) #30

Add link to collections API overview to scaladoc of collection classes (SI-5280) #30

Conversation

joshmarcus commented Dec 5, 2011

joshmarcus commented Dec 5, 2011