Mike Slinn
ScalaCourses.com

Reading Scaladoc

— Draft —

Published 2014-01-02. Last modified 2019-04-22.
Time to read: 4 minutes.

Scaladoc is both the name of a program that reads a project's Scala source code and generates documentation, and the name of the generated documentation. This lecture only discusses how to work with the generated documentation, so the term Scaladoc in this lecture pertains to the generated documentation and not the program called scaladoc.

Scaladoc is like Javadoc with a more capable user interface. Like Javadoc, Scaladoc is HTML-based documentation, created by the scaladoc program after it parses source code. Scaladoc only documents Scala code. Scaladoc has some extra features, and its user interface has evolved considerably from its roots. This lecture shows how to take advantage of the new Scaladoc user interface introduced with Scala 2.12.

Prior to Scala 2.12, Javadoc’s HTML frame-based layout was also used by Scaladoc. This does not work very well on mobile devices, unfortunately. Here you can see them side by side for comparison purposes.

With the advent of Scala 2.12, Scaladoc moved to a single-frame page with a responsive layout, for greater utility with mobile devices. Scaladoc 2.12 looks quite different as a result. You can read how the changes were made from this pull request.

The Scaladoc for the current version of the Scala language can always be found at https://www.scala-lang.org/api/current. Let’s explore it now. (BTW, the Scaladoc for Scala 2.13-RC1 is at https://www.scala-lang.org/api/2.13.0-RC1..

Packages

As you know, Scala source files are organized into packages. The first page of Scaladoc for a project always displays the root package’s package-level overview documentation.

The top of the Scaladoc page features a search field. If you type int into that field, this is what you see:


Notice that the packages and classes shown are now filtered such that only those entries that contain the search term are now displayed.

Classes, Traits and Companion Objects

  1. The first displayed type is Int, and there are small O and C icons to the left of the class name. If you click on them you will be presented with the documentation for the Int companion object and the Int companion class, respectively. We discussed classes in the Classes Part 1 and matchurl=lecture_scalaClasses2.html lectures, and companion objects in the Objects lecture. If you click on the word Int, the Int class documentation is displayed. A green circle with the letter C is displayed to the left of the class name to remind you that this is the documentation for the class.
  2. Let’s click on the letter C in the green circle. Now the Int companion object is shown, and the letter O is shown in a blue circle. Clicking on a circle takes you to the dual; in other words, if the companion object is displayed, and therefore a large O is displayed, clicking on the large O will cause the companion class to be displayed, and vice-versa.

    About 10% of the population is color-blind to some extent, so those people will need to rely on the large O or C symbols to the left of the class name in the main frame.

Source Code

If source code is available, it can be viewed for the displayed class, object or trait by clicking on the file name to the right of the word Source.

Inheritance Hierarchy and Visibility

In general, the inheritance hierarchy for a type includes supertypes and subtypes.

  1. If supertypes exist the Linear Supertypes link will be shown; clicking on it will reveal the supertypes.
  2. If subtypes exist, the Known Subclasses section will be shown. This is a misnomer, because this section might display traits as well as classes. The Types vs. Classes section in the Classes Part 2 lecture discusses the difference between types and classes. Int has no subtypes, so lets look at the scala.collection.BitSet trait’s subtypes. most of these subtypes reside in the scala.collection.immutable package: BitSet, BitSet1, BitSet2, BitSetN, and there is one class that resides in the scala.collection.mutable package, also called BitSet:
  3. The Content Hierarchy section is supposed to appear next. This section can be very informative, so be sure to open it up if present. Not only can you see the inheritance hierarchy visually, but you can also see implicit classes that reference the class you are viewing. Unfortunately, Scala 2.12 broke this feature so it is often missing. Here is the content hierarchy diagram for the scala.collection.parallel.immutable package.
    All of these classes are clickable.

Methods and Properties

  1. The displayed properties and methods for the displayed type or package object can be filtered by typing into the text field containing the text Filter all members. Unfortunately, this feature is broken in Scala 2.12.1.
  2. If you hover over the search bar, a small triangle appears. Clicking on the triangle reveals search options, none of which work.

    You can return to viewing the artifact’s properties and methods by clicking on the Alphabetic ordering link.
  3. When viewing By inheritance, you can cause the inherited properties and values to be displayed by toggling the links in the Inherited section. You can even toggle the visibility of the displayed artifact’s properties and methods here.
  4. Two convenience links are provided: Hide all and Show all. Hide all deselects all inherited classes, traits and interfaces. Show all shows them all, except Any and AnyVal; if you want to include their properties and methods you must click on them.
  5. Visibility controls whether only public methods and properties are displayed, or if all methods and properties are displayed.
  6. Clicking on a type’s method or property will expand that entry so all its information is displayed. Here I have expanded BitSet’s & method:
Previous lecture:

Next lecture:
* indicates a required field.

Please select the following to receive Mike Slinn’s newsletter:

You can unsubscribe at any time by clicking the link in the footer of emails.

Mike Slinn uses Mailchimp as his marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp’s privacy practices.