docs.scala-lang icon indicating copy to clipboard operation
docs.scala-lang copied to clipboard

Scala 3 experimental features should be more clearly labeled as experimental

Open SethTisue opened this issue 1 year ago • 1 comments

in the chat rooms we've seen people bitten by this over and over and over again

I've lost track of how many dozen confused/disappointed people we've had to inform that -Yexplicit-nulls is half-baked and it shouldn't be surprising when stuff doesn't work all over the place

it's very easy to land on one of the experimental features via Google or some other way and then fail to notice in the outline in the left that you're in the "experimental" section

some of the pages on individual experimental features do a good job of warning you, others less so

the page on -Yexplicit-nulls especially doesn't do a very good job; it describes the feature as "opt-in", but it doesn't require a language.experimental import and we cannot expect most Scala programmers to be aware that -Y is supposed to be a signal that something is experimental and/or internal. Scala veterans know this; many others do not.

SethTisue avatar Feb 16 '24 02:02 SethTisue

I think there should be issues filed or PRs against the explicit-nulls doc page to make clear that the experimental nature should be more emphasized. Same for other doc pages that are not clear enough on this.

Also alert reviewers to have an eye on this.

odersky avatar Feb 16 '24 09:02 odersky