Document features conditional on source and target versions

[adriaanm]

-Xsource:2.13

• case classes must have a non-implicit parameter list (https://github.com/scala/scala/pull/5585)
• empty character literal (use '\'' for single quote) (https://github.com/scala/scala/pull/5727)
• Only methods can be marked @elidable. (https://github.com/scala/scala/pull/5539)
• Higher-kinded type variable unification (https://github.com/scala/scala/pull/6069)
• eta-expansion is changing (TODO: document when changes are in M4)
• changes to the computation of the parts of the type of an implicit value (https://github.com/scala/scala/pull/5867, https://github.com/scala/scala/pull/6074)

[SethTisue]

this is for 2.12? where would such documentation go?

[eed3si9n]

Related https://github.com/sbt/sbt/issues/3123

If there were command line entry point that lists out list of flags, -Xsource manuals, latest book recommendations by Scala team, I'd love to surface them as an sbt task scalaHelp.

[SethTisue]

we now have a place to put this stuff: https://github.com/scala/docs.scala-lang/issues/1058

[SethTisue]

nowadays, this would be about -Xsource:3.0 instead

[som-snytt]

I don't know about documenting, but I meant to add 3 to the migration guide. I'm pretty sure it's underused, because otherwise people would be complaining about it. It has, for instance, "infix on the next line." I wish 2.13 were compiled with it.

[SethTisue]

and nowadays it's -Xsource:3 and people are actually using it prepare to migrate to 3, so it's reeeeeallly time now

[SethTisue]

It would also be good to document what effect -target has on generated bytecode. (I've updated the issue title accordingly.)

For the most part it just sets the bytecode version number, but I know of one PR where it actually affects code generation, namely: https://github.com/scala/scala/pull/9556 ("Use StringConcatFactory for string concatenation on JDK 9+")

I didn't find anything else like that when prepping through the compiler code, but it's conceivable I missed something.

[SethTisue]

The pressure to document -Xsource:3 properly is increasing, as seen on e.g. https://github.com/scala/scala-dev/pull/850 (discussion about 2.13.12 release notes). We've seen in the community build that more and more OSS projects are leaving -Xsource:3 enabled in their builds, and each successive recent 2.13.x release has added additional behavior to it.