Although I have been using Scala for a while now, I’m still an explorer of the language and sometimes find myself looking up a compiler warning/error message on the web.
Wouldn’t it be nice if the a given message will include a link to a web document that gives resolution tips, examples etc? That link can be one of the following:
Official Scala documentation reference, if such a link exists.
Stackoverflow or other 3rd party site that gives a good explanation.
Just a google search link for the non-specific message (without the code quotes given by the compiler).
I’m one of the core developers working on Dotty, the next generation Scala compiler. A lot of focus for us is improving the user experience with Scala.
Currently, I’m also working on improving the documentation generator for Dotty, and it will support markdown as well as featuring a static site generator to house documentation (so no longer just the API!). We might start linking things there once dottydoc is generating Dotty’s static site, but for now we’re shooting for having these explanations being available under a -explain flag (as mentioned in the blog post).
As an added bonus, here’s a screenshot from today’s hacking on dottydoc:
The error numbers exist because we wanted to have something that would not change even if the error name changed. I.e we could link to something like: www.dotty-lang.org/errors/e001.html
But having the documentation inline, is currently working better since no such infrastructure is in place.
I would definitely welcome a PR with an ADT for ErrorKinds and for sure an elimination of the manual assignment of error numbers. That being said, Dotty is a compiler and we cannot guarantee complete binary compatibility. These two factors mean that we can’t use sbt plugins, scala artefacts or macros to solve this.
EDIT: to clarify, we cannot support a solution for the error numbers where they are prone to change. E.g we have three error messages: A, B, C. Then someone adds A, A2, B & C - which has to preserve A = 1, B = 2, C = 3 & A2 = 4 (on mobile, so sorry for the convoluted explanation).
EDIT2: perhaps we could consider removing them - ping @smarter
The benefit of stable identifiers probably outweighs the annoyance of maintaining them by a large margin. Maybe a test with some run time reflection trickery could guarantee uniqueness, though that doesn’t help much with manually assigning them.
@soronpo While the Dotty guys are implementing these features and improving docs for compiler warnings/errors, would you consider doing so in Scalac? I believe that you won’t need a lot of knowledge about the internals of the compiler to do this and this could drastically improve the UX for scalac users before the Dotty migration is in place. This is a fantastic idea and I’m pretty sure that if you decide to work on it you’ll have help from other Scala contributors!
@jvican I already took a look at the code to see if this can be implemented generally by creating a google search link for the message. Lets take a look at an example from this group of scalac warnings.
if (settings.noAdaptedArgs)
context.warning(t.pos, adaptWarningMessage("No automatic adaptation here: use explicit parentheses."))
else if (args.isEmpty) {
if (settings.future)
context.error(t.pos, adaptWarningMessage("Adaptation of argument list by inserting () has been removed.", showAdaptation = false))
else {
val msg = "Adaptation of argument list by inserting () is deprecated: " + (
if (isLeakyTarget) "leaky (Object-receiving) target makes this especially dangerous."
else "this is unlikely to be what you want.")
context.deprecationWarning(t.pos, t.symbol, adaptWarningMessage(msg), "2.11.0")
}
} else if (settings.warnAdaptedArgs)
context.warning(t.pos, adaptWarningMessage(s"Adapting argument list by creating a ${args.size}-tuple: this may not be what you want."))
On the one hand, if we had overloaded context.warning with a new definition that adds a link to google search, then google will be hit with specific code that will render the search useless. On the other hand, to now go and manually change the code of scalac in every specific location with a proper documentation link is tedious work. Even if we have those who wish to do so (I actually wanted to contribute this way), then what links do we use? If we wish to point to 3rd party links, what if they become obsolete? If we use a PR to scalac, when will it be merged? Will links be added only on scalac version updates?
All of the above questions led me to suggest the following solution. We create a dedicated scalac webquery redirect service. The service will be have its errors/warnings database as a github project (or part of the scalac project). There anyone can contribute and set the proper link or document that helps the given search. One of the good things is that this service is backwards compatible and can be used to copy-paste error messages from older scalac version errors. IDEs can also use this service to connect you directly. The service will, of course, be able to distinguish between the specific and non specific error messages. With this service we can now overload context.warning and context.error to add a general link.
This service can also be extended to search for anything scala, but I think google is good enough for this.
This is a good idea, but why don’t we reuse the scaladoc to show all the information about errors? I was thinking something along these lines: you create an ADT representing errors that takes as parameter the context information necessary to create the report and then put all the information on these errors as scaladoc comments in every node of the ADT (with examples of why they happen). When this is merged into Scala, error information will be in the published scaladoc for the pertinent Scala version.
Then, to reply to your “what links do we use” we could programmatically generate scaladoc links based on the name of the error class (this may require small changes in scaladoc, but should be very straightforward). This is a similar approach to the one taken in Dotty (this is how you add an error), though the online documentation is not a feature yet implemented.
With my previous suggestion, 3rd party links won’t be necessary as everything can be done in scaladoc (and we control it). Therefore, they won’t ever become obsolete.
I don’t suppose the changes to make this work are going to be incompatible, so it could be merged as soon as the compiler maintainers review it (depending on the required workload, that could be 2.12.3 or 2.12.4). I’m pinging here @adriaanm and @SethTisue in case they can shed some light on this and also voice their interest in this feature.
@vossad01 I’ve seen your interest in contributing to several open-source Scala projects. If you’re interested in this feature, you could perhaps work together with @soronpo; this is a feature that would greatly improve the Scala experience and it does not look like it requires internal knowledge of the compiler. I’m also happy to get you started and guide you if you need any help – team work is great!
