in Scaladoc, be clearer that asInstanceOf is unsafe (and platform-dependent)

[robstoll]

see https://contributors.scala-lang.org/t/pre-sip-deprecate-asinstanceof-introduce-unsafeasinstanceof/6568
for the motivation behind this change

[SethTisue]

It's good to add these cautions, but perhaps it would also be good to give some indication of what the method is for.

[robstoll]

@SethTisue I actually woke up this morning and thought the same 😄 without an explanation for what it is intended for, it makes it look like the method shouldn't be there in the first place.

I'll rework the doc, thanks for all input

[som-snytt]

Abandon all hope, ye who enter here. is the traditional messaging.

[Sporarum]

I think the comment is a bit overly wordy
Notably the example of what happens on JDK8 is in my opinion superfluous
(I don't think we should sacrifice clarity for brevity, but in this case making it smaller makes it easier to read, without impacting clarity)

[sjrd]

Overall I think this new doc spends too many words talking about all the things that could happen in bad situations. It should focus more on what happens in good situations. Then have a section at the end that makes it clear, without giving a dozen examples, that bad casts have undefined behavior. Two examples should be enough: one with an expected JVM-style CCE failure, and one with unexpected "success".

[SethTisue]

@robstoll just wanted to say thanks for writing and updating this — we're making suggestions for adjustments, but it's super helpful to have somebody step up with that initial draft

[robstoll]

@SethTisue the review is appreciated and necessary. In the end we will have hopefully a better version than the current.

I have one question though, seeing that isInstanceOf mentions union types I figured this doc is for scala 2 and scala 3. Is this correct?

[sjrd]

I have one question though, seeing that isInstanceOf mentions union types I figured this doc is for scala 2 and scala 3. Is this correct?

Yes, the library, and hence the doc, is shared between Scala 2 and 3.

[robstoll]

@som-snytt @Sporarum @sjrd @bishabosha @SethTisue pushed, please review again

[He-Pin]

Better to add some doc about the resulting bytecode(Java) vs patten matching, as https://github.com/JakeWharton/confundus

[robstoll]

@He-Pin see the first commit, I had examples of the resulting byte code (in prosa) and it was a consensus of the reviewers that those are too much detail

[Sporarum]

I think it's better than before, but still seems overly wordy.

I'm not super familiar with scaladoc formatting, would it be possible to use the "one sentence = one line" convention ?
If yes, I would be in favor of changing this doc to that format
(And all other doc, but this is outside this PR's scope)

[robstoll]

I think it's better than before, but still seems overly wordy.

I'm not super familiar with scaladoc formatting, would it be possible to use the "one sentence = one line" convention ? If yes, I would be in favor of changing this doc to that format (And all other doc, but this is outside this PR's scope)

@Sporarum me neither, do you mean start every new sentence on a new line?

[Sporarum]

I think it's better than before, but still seems overly wordy.
I'm not super familiar with scaladoc formatting, would it be possible to use the "one sentence = one line" convention ? If yes, I would be in favor of changing this doc to that format (And all other doc, but this is outside this PR's scope)

@Sporarum me neither, do you mean start every new sentence on a new line?

Yes, doing the following for example:

-   *  On a language level it merely tells the compiler to forget any type information it has about
-   *  the receiver object and treat it as if it had type `T0`. How the compiler manages to transition from the type 
-   *  of the receiver object to `T0` is unspecified and should be considered an implementation detail of the 
-   *  corresponding compiler backend and can vary between target platform and the target version.
-   *  Transitioning to T0 might involve inserting conversions (including boxing/unboxing), casts, default values or
-   *  just no real operation at all.
+   *  On a language level it merely tells the compiler to forget any type information it has about the receiver object and treat it as if it had type `T0`.
+   * How the compiler manages to transition from the type of the receiver object to `T0` is unspecified and should be considered an implementation detail of the corresponding compiler backend and can vary between target platform and the target version.
+   *  Transitioning to T0 might involve inserting conversions (including boxing/unboxing), casts, default values or just no real operation at all.

[robstoll]

I think it's better than before, but still seems overly wordy.
I'm not super familiar with scaladoc formatting, would it be possible to use the "one sentence = one line" convention ? If yes, I would be in favor of changing this doc to that format (And all other doc, but this is outside this PR's scope)

@Sporarum me neither, do you mean start every new sentence on a new line?

Yes, doing the following for example:

-   *  On a language level it merely tells the compiler to forget any type information it has about
-   *  the receiver object and treat it as if it had type `T0`. How the compiler manages to transition from the type 
-   *  of the receiver object to `T0` is unspecified and should be considered an implementation detail of the 
-   *  corresponding compiler backend and can vary between target platform and the target version.
-   *  Transitioning to T0 might involve inserting conversions (including boxing/unboxing), casts, default values or
-   *  just no real operation at all.
+   *  On a language level it merely tells the compiler to forget any type information it has about the receiver object and treat it as if it had type `T0`.
+   * How the compiler manages to transition from the type of the receiver object to `T0` is unspecified and should be considered an implementation detail of the corresponding compiler backend and can vary between target platform and the target version.
+   *  Transitioning to T0 might involve inserting conversions (including boxing/unboxing), casts, default values or just no real operation at all.

I leave that change to someone else, I think we should still adhere to 120 chars max per line

[SethTisue]

still seems overly wordy

I agree. I've pushed a commit that shortens this considerably, while still preserving what's most important, in my judgment anyway.

[lrytz]

Looks very good. Thanks all for the discussion and turning it into a concise explanation.

[SethTisue]

I've merged this since 2.13.14 is imminent, and since further improvements can always go in followup PRs.

But I note that we lost this:

Note that the success of a cast at runtime is modulo Scala's erasure semantics.
Therefore the expression 1.asInstanceOf[String] will throw a ClassCastException at runtime, > while the expression List(1).asInstanceOf[List[String]] will not.

The new text just talks about "erased" and "erasure" without making it really concrete like this. I guess this was because we wanted to be scrupulous about not documenting JVM-specific semantics? It might be good to add something like this back while being clear it's describing the JVM behavior specifically?

On the other hand, the Scaladoc of a particular method isn't the place to launch into long explanations of background about language semantics, what even is type erasure, and so on. But I'm not sure we have a doc page to link to that does explain that stuff.