How to Navigate the Scaladoc Interface (2.10/2.11)

It might be surprising to see a “how to” for navigating the Scaladoc interface. Since I’ve started using Sublime for Scala development I’ve come to heavily rely on the Scaladoc for any library I’m using. I’ve come across a few nuances that might be hard to notice at first glance. This post is my attempt to document those nuances and a little guide on how to be more effective in navigating the generated documentation.

The Scaladoc interface is teeming with features that don’t seem to have any documentation. We need documentation for our documentation system. How meta! That said, Dick Wall has recorded a screencast called Using the Scaladoc Interface which you should definitely checkout.

This post will cover some of the features he highlights plus a few more.

• Website Layout
• Searching
• Displaying Results
  • Matched Content Area
    • Member Search Bar
    • Member Definition Area
      • 1. Type Members
      • 2. Concrete Value Members
      • 3. Abstract Value Members
      • 4. Instance Constructors
      • 5. Implicit Value Members
      • 6. Shadowed Implicit Value Members
• Miscellaneous

Website Layout

The Scaladoc website is separated into 2 main windows:

1. The Search Window.
2. The Results Window.

Clicking on the Layout Toggle Button (1) allows you to hide the Search Window and focus only on the Results Window. You can also drag the divider to change the window sizes.

These windows can be broadly subdivided into three main components:

1. The Entity Search Bar on the top left. This allows you to search by top-level entities such as packages, classes, traits and objects. Nested or path-dependent types, methods and variables (val and var) and any entity with symbolic characters in its name can’t be searched from here.
2. The Search Results List found just below the Entity Search Bar, which displays any matched results based your query.
3. The Matched Content Area in the Results Window displays a selected search result in more detail.

NB: The names for the various areas mentioned above are my own. I have been unable to find any documentation on what these areas on the website are actually called. If you know the actual names of these areas in the interface, please let me know and I will update this post.

This is a simplified view highlighting the main areas. We’ll go into detail about the other areas later.

Searching

Searching is primarily done within the Search Window. To find an entity such as a class, you can type in the name of the class into the Entity Search Bar and the Search Results List will display only matching results, grouped by the packages they are in.

1. The search has both case-sensitive and case-insensitive functionalities. If you start the search with an uppercase letter, the search is case-sensitive from that point onwards. In the example below, we search for BitSet with the exact case and we get a number of matches (1). If we don’t use the correct case we get no matches (2).

If you keep all the letters lowercase, then the search is case-insensitive. In the example below, the search is all lowercase characters and results in the same matches as that of the exact case (1).

2. The search is a wildcard and will match any top-level entity name with that text in it, including packages.

3. You can also match on mnemonics of your class name. In the example below we use LHS to find LinkedHashSet class.

4. If you search by entering a package path, the results will be filtered to include only the specified package and sub packages.

5. You can also search by typing in the full package path to the entity.

If you don’t want to type in the full package path to an entity, you can simply use the last subpackage of its package path along with the entity. In the example below we search for scala.collection.immutable.Seq by searching for immutable.Seq.

6. Clicking on the focus link on a package header in the Search Results List will constrain the search to only include entities within the focussed package.

In the example below we focus on scala.collection.immutable and then search for List. The results are limited to matches in the scala.collection.immutable package.

7. Clicking on the display packages only filter will only show packages in the Search Results List. If a search term is in the Entity Search Bar, then only packages matching the search term and packages with entities that match the search term will be displayed.

Clicking on the display all entities filter clears the package filter.

8. When displaying only packages, use the show and hide filter on the package header to expand and collapse entities within that package, respectively.

9. Pressing ESC clears any search terms in the Entity Search Bar.

Displaying Results

Once we have some matches in the Search Results List, we can open them in a number of ways:

1. Clicking directly on the package header will open the package documentation for that package in the Matched Content Area.

2. Clicking on the name of a class, object or trait will open its documentation in the Matched Content Area. Clicking on the class (1), object (2) or trait (3) icon will open the corresponding entity documentation in the Matched Content Area.

3. After entering a search in the Entity Search Bar, pressing the down arrow will allow you to navigate through the Search Results List. Pressing enter on any result will open its documentation in the Matched Content Area.

4. Clicking on the deprecated filter in the Search Window, will open up the Matched Content Area with all the deprecated members in the api. Members include types, path-dependent types, methods, implicits and variables.

5. The clicking on any letter on the alpha bar (1) will open up a list of all members starting with that letter in the Matched Content Area.

In the example below, we click on the letter T to search for the path-dependent type TypeSymbol.

6. Clicking on the #(symbol) filter (1) will open up a list of all members with special-charactered names in the api.

Next lets look at the Matched Content Area in more detail.

Matched Content Area

There’s quite a lot of detail in this area. Here’s an overview of some items of interest.

1. The entity type is shown on the top left.

There are five different icons for packages, classes, traits, objects and path-dependent types. If any types other than packages, have a related companion object or extractor, or a companion object or extractor has a related type, then this relationship is depicted by the sticker peal overlay. Clicking on the sticker peal overlay takes you to the companion object or extractor from the type or to the type from the companion object or extractor. Here are the icons mentioned in the above scenarios:

2. The package breadcrumb path allows you to click through to any sub package for a type.

3. Any traits or classes extended by the type. You can navigate to any of these super types through their hyperlinks.

4. If this type has a companion object or extractor, then similar to clicking on the sticker peal icon, this link will take you to the companion object or extractor. If this is the companion object or extractor of a related type, this link will take you back to the related type.

5. Link to the package documentation for this type.

6. The entity documentation. This is usually an overview of the type and what it is used for. There might be some handy example usages in there as well.

7. Any linear supertypes or the order in which supertypes are resolved. From Scala Design Patterns:

traits offer a form of multiple inheritance. In such cases, the hierarchy is not necessarily linear, but forms an acyclic graph that needs to be flattened upon compilation. What linearization does is this: it specifies a single linear order for all of the ancestors of a class, including both the regular superclass chain and the parent chains of all of the traits.

8. All known subclasses with handy hyperlinks.

9. Link to the source file where this entity is defined. This is one of the most useful features of Scaladoc. :)

10. The Member Search Bar will let you search within the Matched Content Area for available members.

11. Filters that can be applied to the results.

    

    • Ordering lets you order the results Alphabetically or By Inheritance or by a Grouped category. Alphabetic ordering simply orders all members alphabetically (a-z) within each member section. Ordering by inheritance, orders members by which supertype they are defined on. Grouped orders members across some predefined grouping created by the Scaladoc author. See scala.reflect.api.Symbols for an example of this.

    • Inherited allows toggling members defined in any combination of supertypes. This is useful to find out where a method is defined when you have a complex inheritance hierarchy.

    • Implicitly defines which additional methods are available via implicits defined in scope.

    • Visibility restricts members to either Public modifier scopes or All scopes other than private.

12. Defines various member definitions sections. See the Member Definition Area for more details.

13. The package documentation for a package, has a Content Hierarchy diagram that describes the relationship between the types within that package.

14. Types that have been annotated with a @contentDiagram tag, generate a Type Hierarchy that describes the relationships between a type and its super and sub types.

Member Search Bar

To find a member, type in a query into the Member Search Bar.

1. The search is completely case-insensitive; Content is matched irrespective of case.
2. You can’t use a mnemonic search like in the Entity Search Bar.
3. You can search on any text in a member description. In the example below we search for the text w.r.t and matches are found in member descriptions.

4. You can’t directly search against types in method signatures for example. They have to be mentioned in the description for a match to be found. In the example below we search for GenTraversable within the scala.collection.immutable.Seq documentation. While GenTraversable is used in method definitions there are no matches returned from the search because GenTraversable is not mentioned in any descriptions.

If we perform a browser search on the same page for GenTraversable we find search hits.

4. You can tab between the Member Search Bar and the Entity Search Bar. I’m not sure how useful this really is but it’s there if you need it.

5. Pressing ESC clears any search terms in the Member Search Bar.

6. You can’t only search for a def for example and exclude other members such as a val. Searches of the type:

def [method_name]

yield nothing. The browser search doesn’t match queries like the above either. As an example, if we search for the following through Chrome:

def collect

on the members of scala.collection.immutable.Seq, we don’t find any matches. This is annoying as the collect method is clearly defined in the documentation.

Member Definition Area

There is some commonality between the features available to the different member types. Many of the features available in one member type can be found in other types as well.

Member definitions can be separated into six areas.

1. Type Members

Path-dependent types (nested types).

1. The name of the path-dependent type. Although there is no visible hyperlink to the the class name (underline), it is in most cases a hyperlink and can be clicked to go through to the type’s documentation. This had me confused for a while.
2. The summary of what the type is about.
3. Any other types extended by this type. All supertypes are linked and can be navigated.
4. Dropping this arrow down will reveal some additional information about this type.

5. The parent type where this nested type is defined.

2. Concrete Value Members

Members that have an implementation.

1. The member definition, with parameter and result types hyperlinked.
2. Description of the method, including parameters, types and results.
3. Full signature. This is present if the member definition (1) is simplified, which can be identified by the [[use case]] ascription. In the above case, the member definition (1) does not mention the CanBuildFrom implicit which is shown in the full signature.
4. Where in the inheritance hierarchy this method is defined. In the above case the ++ method is defined in GenTraversableLike and then overridden in TraversableLike.
5. Permalink to this member, which embeds the method signature in a URL which can be used to link straight to ++ method documentation.

http://www.scala-lang.org/api/2.11.8/index.html#scala.collection.GenTraversableLike@++[B](that:scala.collection.GenTraversableOnce[B]):scala.collection.GenTraversable[B]

3. Abstract Value Members

Members that are abstract (1) (have no implementation).

4. Instance Constructors

Constructors for creating an instance of the type.

5. Implicit Value Members

Implicit members:

1. Implicit types (usually classes) are defined with the Type members.
2. Implicit values (var, val and def) are defined with the Value members.

6. Shadowed Implicit Value Members

Implicit members that are not applicable due to existing implementations.

1. Member supplied by an implicit conversion.
2. Where implicit comes from and when it gets applied.
3. How to use the shadowed implicit (see below for an explanation) by using a type ascription.

Implicit conversions can be used to add methods to a type which doesn’t have those particular methods (“pimping”). If the target type already has a method with the same signature (name and types) that the implicit conversion is trying to add to it, it is termed “shadowing”. The definition of the method on the target type takes precedence over the implicit conversion which is not applied. A type ascription can be used to manually specify which method definition to use.

From What is “Shadowed Implicit Value Members” in Scala doc?:

case class Foo(x :String) {
  def whoAmI = "Foo: " + x
}

implicit class Bar(foo: Foo) {
  def whoAmI = "Bar: " + foo.x
}

println( Foo("test").whoAmI ) //prints Foo: test
println( (Foo("test"): Bar).whoAmI ) //prints Bar: test

Miscellaneous

1. If you know the package path of the member you are looking for, you can append it to the documentation URL with a # to go directly to the documentation. In the example below we go directly to the scala.concurrent.Future documentation by adding it to the Scaladoc API URL:

"http://www.scala-lang.org/api/2.11.8/index.html" +
"#" +
"scala.concurrent.Future"

The above link takes you to the Future type documentation.

If you want to go to the Future object, then add $ to the end of the path to the type documentation.

"http://www.scala-lang.org/api/2.11.8/index.html" +
"#" +
"scala.concurrent.Future" +
"$"

If you want to go to a path-dependent type, then use the above formula and use a $ between the parent type and the nested type. In the example below if we want to go the documentation for TypeSymbol which is a nested type of scala.reflect.api.Symbols we would write the link as:

"http://www.scala-lang.org/api/2.11.1/scala-reflect/index.html" +
"#" +
"scala.reflect.api.Symbols" +
"$" +
"TypeSymbol"

This unfortunately doesn’t work as expected for all types. The location of the documentation for a member depends on where it is defined. Taking scala.collection.immutable.Set as an example, if we want to see its WithFilter path-dependent type’s documentation, we might incorrectly assume the documentation URL is:

"http://www.scala-lang.org/api/2.11.8/index.html" +
"#" +
"scala.collection.immutable.Set" +
"$" +
"WithFilter"

But the above doesn’t work because WithFilter is defined on scala.collection.TraversableLike. This link works:

"http://www.scala-lang.org/api/2.11.8/index.html" +
"#" +
"scala.collection.TraversableLike" +
"$" +
"WithFilter"

Also as mentioned previously, you can bookmark a permalink to any member and use that to go directly to any documentation.

That about covers it for the overview of the Scaladoc interface. If I’ve missed any useful tips or misunderstood a feature, please let me know in the comments section below.