reflectiveCalls warning is not clear on where to look in API

[scabug]

When you have code that results in a structural type member, you get the below warning:

reflective access of structural type member method foo should be enabled
[warn] by making the implicit value scala.language.reflectiveCalls visible.
[warn] This can be achieved by adding the import clause 'import scala.language.reflectiveCalls'
[warn] or by setting the compiler option -language:reflectiveCalls.
[warn] See the Scala docs for value scala.language.reflectiveCalls for a discussion
[warn] why the feature should be explicitly enabled.

Specifically take note of :
See the Scala docs for value scala.language.reflectiveCalls for a discussion

The problem is that if you go to the reflectiveCalls trait, there is no documentation. Whereas if you go to the language object and look at it's reflectiveCalls val, then you will see the documentation.

The natural inclination from the above warning is to review the trait, so either the trait needs to contain the documentation, or the warning needs to be made more clear as to the location of the documentation.

[scabug]

Imported From: https://issues.scala-lang.org/browse/SI-9631?orig=1
Reporter: @JustinPihony
Affected Versions: 2.12.0-M3

[scabug]

@heathermiller said:
Thanks for the report. Though, the warning does say: See the Scala docs for value scala.language.reflectiveCalls for a discussion

It says "value scala.language.reflectiveCalls"... That's explicitly telling you that it's a value and that it can be found in the scala.language object. You link to trait "scala.languageFeature.reflectiveCalls" which is not the path that the warning instructs one to consult.

This is the same error message for all language imports (HKT, implicit conversions, etc), and in years of it being in use, so far I can't say that I've heard any complaints that this warning not precise enough. It actually is quite precise. Therefore, I can only recommend to close this issue, as it appears that the reporter did not notice the word value in the warning.

[scabug]

@som-snytt said:
In Eclipse, it's tricky to navigate to the val, while ctl-shift-T (open type) shows the trait.

Autocomplete of an import shows the Scaladoc, but once I've entered the source text, my hover doesn't show Scaladoc for imports.

I have to F3 (open declaration) on the import to get nice Scaladoc hovers.

ctl-shift-T also opens the language object, but one might think naively that language is a package and reflectiveCalls is an object.

Wording such as, "See the reflectiveCalls value member of the scala.language object," may be warranted.

I'm not suggesting Eclipse could display a direct link in the error message, which would be an amazing feat of something.

[scabug]

@JustinPihony said:
@heathermiller, while I agree that the message states that it is a value and points to scala.language instead of scala.languageFeature, the natural inclination when you receive this warning is to google for the more unique keyword: reflectiveCalls*. Which, this leads you to the trait that I referenced. At which point, you are blinded by confirmation bias that you found the documentation for reflectiveCalls and begin to confuse further. It ends up being a problem like finding an O instead of a 0. Scala already takes some flak when it comes to areas of confusion, so I see a change like this as a way to help shore up those areas.

As to the origin of this issue, it comes from a customer who was exactly confused as I specified. Take that with what A. P. Mark said, along with this StackOverflow question and there are indeed cases where people have brought this up. And, those are just the cases that are public. It is entirely possible that there many more cases where the dev finally figured it out after wasting undue time simply finding the correct documentation. Again, erring on the side of clarity couldn't hurt here.

*I realize that this is true of all language imports, I simply chose one for specificity.

[scabug]

@heathermiller said (edited on Jan 27, 2016 3:54:17 PM UTC):
The SO article pointed to is irrelevant to this issue–that user doesn't know what language feature they're using, and he didn't understand the terminology on the (correct) Scaladoc page either. His trouble wasn't that he couldn't find the documentation because he didn't completely read the warning message. This bug report claims that this sentence: "See the Scala docs for value scala.language.reflectiveCalls for a discussion" is not enough to know that reflectiveCalls is a value member of scala.language, which I disagree with.

Furthermore, you make the point that you just want to search "reflectiveCalls" and ignore the path. I don't think it's a wise way to use Scala or Java to totally ignore paths when trying to debug code.

RE: A.P Marki – I don't think this is an issue of tooling. This is simply an issue of someone overlooking the word "value" in the explicit instructions in the warning. This is a bug report that seems to request that we change our warnings so that people don't have to think about paths, which is not the right thing to do in my opinion.

[som-snytt]

Apparently, the customer was not always right.