Scala 3: How to search the Scaladoc with function signatures

By Alvin Alexander. Last updated: September 28, 2021

A great new feature in the Scala 3 Scaladoc is that you can search for methods by supplying a method/function signature. For instance, imagine that you’re new to Scala, and you have this list:

List("Ken", "Frank", "Lori")   // A

Furthermore, you know that you want to get to this list, which contains the length of each string in the first list:

List(3, 5, 4)                  // B

Being a beginner to Scala, you know that the collections API has over 100 functional methods, but you might not know which method will get you from A to B. Wouldn’t it be cool if there was a way to search for the function you need to get from A to B?

Enter Inkuire

With the Scala 3 Scaladoc, you can search for function signatures using a tool that’s built into the Scaladoc named Inkuire. Going back to the example, you know that you have a list of this type:

List[String]

and you also know that you want a resulting list of this type:

List[Int]

So it would be awesome if you could search for this:

List[String] => List[Int]

Unfortunately the search feature doesn’t currently match that desire, but if you happen to be comfortable with Scala’s function syntax — which is used consistently with anonymous functions, function signatures, and more — you’ll know that you can search for this:

List[String] => (String => Int) => List[Int]

When you do that, you’ll see these search results:

Unfortunately the right side of the search results is also rather intimidating. Both of these steps make me think that it would be awesome if there was a way to toggle both (a) the search functionality and (b) the search results between “I’m an expert” and “I’m a newbie” modes (especially since I think this search feature may be used more by newbies than experts).

But skipping past that commentary, once you know that you need to search using this function signature syntax, when you perform a search like this, you can see on the left side of the results that you’re probably looking for a “map” function. So now if you click on the map method in those results, you’ll be taken directly to the map method Scaladoc, as shown in this image:

If that Scaladoc had an example like this:

List("Big", "Belly", "Burger").map(_.length)   // List(3, 5, 6)

our new Scala developer would be in documentation heaven. :)

I hope you’ll agree that with the ability to search for methods by their signature, and then jump directly to matching methods, there’s a lot of potential in this tool.

Get more generic!

Another excellent feature is that if you’re comfortable with generic types, you can also search the Scaladoc using generic type parameters:

List[A] => (A => B) => List[B]

In the context of Inkuire, that code can be read as, “I have a generic List[A], and I want to search for a function in the Scala API that will let me transform that List[A] to a List[B].”

In this example, if you also happen to know that you don’t necessarily need a List, but any old Seq, you can also search like this:

Seq[A] => (A => B) => Seq[B]

In both of these examples I’ve come to think that Inkuire can be a nice teaching tool, because it helps developers think about function signatures as well as generic types.

Gratitude

I want to thank Kacper Korban of VirtusLab for creating Inkuire, and also for helping me understand the function signature I needed to use to find the map method in this example.

Help on grokking those function signatures

As a shameless plug, if you don’t understand those function signatures — fear not, I didn’t understand them when I started either!

But fortunately I can understand them these days, and I explain them in several recipes in the Scala Cookbook, which has been a best-selling new release on Amazon for at least the first four weeks it’s been available. The book also covers generic type parameters, the map method, and many more methods in the Scala collections API.

If you’re interested in Scala 3, I hope this has been helpful.