Showing Scaladoc and source code in the Scala REPL

After a brief Gitter discussion that starts here and ends here, I decided to take a little time to see:

  • What it would take to show Scala documentation in the REPL, and
  • Different ways of viewing that documentation

As a result I created this Github project:


A few disclaimers before we jump in:

  • This is just a “proof of concept” (POC) or MVP project
  • A lot of the code is written in a “worst practices, no error checking” style because I didn’t expect to spend much time on it
  • Everything in this project is likely to change
  • There is a work-in-progress Scala 3 REPL :doc command that inspired this effort; see those Gitter links for more details

Also, yes, I do know that Ammonite has a src or source command.

Video demo

The easiest way to show this is with a video demo, so here’s an animated GIF. Click the image to see a larger version of it:

[Showing documentation and source code in the Scala REPL]

As shown, you can always type help to see the list of available commands.

How it works

The way it works is that you can currently issue these commands:

Command Description
doc("List") show the List class Scaladoc
doc("List", "withFilter") grep for withFilter in the methods of the List Scaladoc
src("Vector") show the source code for the Vector class
browser("LazyList") open the LazyList class Scaladoc in the default browser
editor("Vector") open the Vector class in your default ".txt" editor

You can also type help to show that help output.

When you issue any of those commands, this code goes out to the internet, gets the Scaladoc for the class you specify, then does whatever it needs to do for each command. The one exception is the browser command, which opens the Scaladoc page in your default browser (but only on a Mac right now).

At the time of this writing, the first doc command has the worst output, so I generally wouldn’t use it. The second command is starting to have decent output, and looks like this:

withFilter(p: (A) => Boolean): WithFilter[A, [_]List[_]]
Creates a non-strict filter of this list.
Creates a non-strict filter of this list (more here) ...

withFilter(f: (A) => Boolean): Iterator[A]
Implicit This member is added by an implicit conversion from 
List[A] toIterableOnceExtensionMethods[A] performed by (more here) ...

NOTE: If the code finds multiple matches for a class name, such as for Map, nothing works, because I don’t handle that case yet.

Of course a better approach is to get this documentation from the Scala source code jars, but because I was trying to limit my time on this project, I took this other approach.

More information

For more information on how to install and use this extremely experimental POC/MVP code, see the Github repo for this project. The README file there shows how to install and run this on your system.