scala / docs.scala-lang

The Scala Documentation website
http://docs.scala-lang.org
559 stars 1.02k forks source link

Scala 3 experimental features should be more clearly labeled as experimental #2976

Open SethTisue opened 6 months ago

SethTisue commented 6 months ago

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.

odersky commented 6 months ago

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.