Document features conditional on source and target versions

[adriaanm]

-Xsource:2.13

• case classes must have a non-implicit parameter list (SI-10097 Error if no non-implicit case class param scala#5585)
• empty character literal (use '\'' for single quote) (SI-10133 Deprecate unescaped single quote char literal scala#5727)
• Only methods can be marked @elidable. (SI-10068 Only permit elidable methods scala#5539)
• Higher-kinded type variable unification (Higher-kinded type variable unification. scala#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 (Include the parts of a compound/refinement type in implicit scope. scala#5867, Resolve implicit instances for abstract types, according to the spec. scala#6074)

[SethTisue]

this is for 2.12? where would such documentation go?

[eed3si9n]

Related sbt/sbt#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: scala/docs.scala-lang#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: scala/scala#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. #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.

[som-snytt]

The PR with Lukas's definitive tweaks:

scala/docs.scala-lang#2994

Now the one that needs documenting is -system:

scala/scala#10801

but that doesn't change behavior per se; -target is relevant again.