Revealing the Benefits

Scaladoc plays a critical role making your code accessible to others, particularly when the luxury of face-to-face contact is not an option. With a few concise words and pointed examples, you can orient the user and get them on a productive track. Scaladoc is an especially good choice for documenting library code. As an example of effective Scaladoc, take a look at the documentation for the Scala Standard Library Regex class (http://www.scala-lang.org/api/current/#scala.util.matching.Regex). With a handful of code examples linked with explanatory text, the class becomes immediately accessible.

Scaladoc is far from the only option for documentation. Some libraries flourish while eschewing Scaladoc almost entirely. Scaladoc sports the key advantage of being embedded in your code and supporting a simple wiki syntax. Nearly all documentation authoring can be accomplished without switching out of your IDE.

Bookending the Continuum

As a Scala developer you already have a good idea of what makes for useful documentation. This helps when you start authoring your own documentation.

Some projects, such as ScalaTest, are ahead of the documenation curve (http://doc.scalatest.org/2.2.6/index.html#org.scalatest.FlatSpec). But how is this layout achieved? You will find out later in this chapter. Let's first examine Scala documentation in general.

Choosing What to Document

Let's explore what type of documentation is useful. If you have coding guidelines that stipulate project documentation requirements then you'll want to use the remainder of this chapter to learn how to unleash the power of Scaladoc. If you have no guidelines, then consider creating a set of documentation objectives.

If, on the other hand, you are developing a library for others to use, you will need to determine if Scaladoc can form part of the adoption path for your end users. If you decide to take this route, later sections in this chapter cover the inclusion of examples in Scaladoc.

One final question to explore is whether you have the opportunity to add Scaladoc after development activities are complete. If the answer is no, then document the code incrementally as you develop it. An advantage of interlacing documentation and development is that there is less context switching. Even when your planned activities include a later documentation phase, you should evaluate bringing this forward and document as you code. The results are better and the net effort will be lower. Let's dive into Scaladoc and discover the many advantages of implementing it.

Overall Layout

The generated Scaladoc is a collection of HTML pages that can be viewed with a browser. The files can reside locally or they can be published on the web. Options for web publication are covered later in this chapter.

These are the files and directory you see after generating the documentation using the scaladoc command:

$ ls -1 scaladocs/
com/
deprecated-list.html
index/
index.html
index.js
lib/
package.html

Navigate to http://www.scala-lang.org/api/ and take a look at the overall layout of the page. You will see in Figure 8.1 how it is divided into two sections: the index pane and the content pane.

The index pane is where you search the documentation. The content pane displays documentation grouped by class, trait, object or package. The UI is unsurprising to use, but investing a few minutes studying each element will pay off. Time to dive in.

Index Pane

Your entry point into the documentation is the index pane shown in Figure 8.2. This pane is partitioned into the search field, the full index, the kind filter, and finally the entities grouped under the package they belong to.

Searching for Entities

When you type text into the search box, the list of entities is restricted. The filtering behavior differs based on the presence or not of capital letters in the search text (see Figure 8.3). When the query term is all lower case, the filter is case insensitive and contains a match on the fully qualified name of each entity.

This example shows packages, classes, and traits.

Including one or more capital letters in the query term applies a camel case match (see Figure 8.4).

The query box has a hidden feature in Scaladoc generated from Scala 2.11.7. Append a dollar to your query term and this works in the same way as if it were part of a regular expression. For example, Map$ will match AbstractMap not ImmutableMapFactory.

Indexing It All

Underneath the query box you will find a horizontal list of clickable letters bookended by a hash and the word deprecated (see Figure 8.5). Clicking any of these elements will show a listing of entities, methods, functions, and public and protected vals and vars.

When you click R you will see what is shown in Figure 8.6.

Under each entry are links to the entities that contain the entry. You should be aware that when the default Scaladoc generation options are used, nested types will not be found from the query box. An example of this can be found in the Z section where Zero is shown contained in Duration, but querying for Z does not show Zero.

Occupying the next slot down you will encounter the kind filter. This toggles between hiding packages and not hiding them. This is useful when you are seeking an overview of the packages. Once you have arrived at the package of interest, click show to reveal the contained entities.

When you have restricted the display to packages, entering query text will automatically turn off the package restriction.

Figure 8.7 shows the index pane restricted by query text with some packages collapsed. This figure also serves to illustrate the entities type indicator: O for object, C for class, and T for trait. Two columns suffice for this as a class, and a trait cannot share the same name in the same package. The O, C, and P letters are clickable and navigate the content pane directly to the entity type. Clicking the entity name navigates to the class or trait unless there is only an object for the name.

Content Pane

The content pane is on the right (see Figure 8.8). After you have clicked on a package, class, trait, or object, information about the selected entity is displayed here. The pane is divided into three sections: top level information, filtering and ordering options, and entity member details. Each section is described in the following text. Before you step though the process of adding Scaladoc to the example project, a quick tour of the notable features of the content pane is in order. ParMap from the standard library has this documentation.

Top-Level Information

Depending on what you select, you will be presented with information regarding a class, a trait, an object, or a package. The types of information that are shown depend on both the type of entity and the entity itself. Objects, for example, will not include a Known Subclasses section because objects do not have subclasses.

Starting from the top and working down you will see a large letter: O, C, T, or P denoting Object, Class, Trait, or Package respectively. Next to this is the entity name. The large letter is clickable. If you start at a class Foo, which has a companion object, clicking the C navigates to the object Foo, and the letter switches to O. One way to think about this is that clicking takes you to the next entity related by name if such an entity exists. There are a limited set of such relationships that can exist:

• Class and Object
• Trait and Object

Over to the right (see Figure 8.8) you find the label Related Docs: introducing links to the related entity if it exists and a link to the package the entity is in. Hover the mouse over the top right to reveal a hidden Scaladoc feature. A link icon appears. Right click and copy to obtain a link to use to navigate directly to the entity page you are currently on. Permalinks are also available for each entity member. See Figure 8.9 for an example.

Following the entity name is the entity signature. This corresponds to the code you find in a source file without the template body. Class parameters, variance annotations, optional superclass, and mixins will be seen here. Hovering over a name will show the fully qualified version of the name.

Residing under the entity signature is the class, trait, object, or package level documentation. The text here is derived from the Scaladoc comments the author added to the entity before the entity header. Beneath the main comment are the type parameter comments, then the attribute block containing, in this case: Self Type, Source, and Since. Later you will see the full list of tags and wiki syntax you can use to directly control the content of the sections described in this paragraph.

Moving down from the attribute block you can see Linear Supertypes that show the supertypes in linearization order. Known Subclasses is self-explanatory. Type Hierarchy shows a view of the type hierarchy centered around the current entity. It shows the directly declared supertype and mixins, implicit views to other types, and some subclasses.

The boxes are clickable and will switch the content pane to the new entity. If you select a package, the Content Hierarchy will be shown. There is also a type hierarchy diagram that shows the entities contained directly in the package. Click the diagram to have it pop up in a larger window.

Filtering and Ordering Options

After the diagrams you are presented with controls for filtering and ordering the member documentation that occupies the remainder of the content pane. The first element is the query box.

Try this out:

• Navigate to http://www.scala-lang.org/api/current/#package.
• Use the index pane filter to filter by LL.
• Pick LinkedList.
• Enter head into the content pane query box. You will see method with head in the method name or description.
• Add tail to the content page query box. The box now contains “head tail” and the listed members swells to include tail and a few other methods.
• Replace the query box content with withFilter.

When you added tail into the query box, you saw a demonstration of the additive nature of the content pane query box. The query for withFilter included WithFilter in turn, demonstrating the case insensitivity of the content pane query. Remember, you saw that the index page search was case sensitive.

Underneath the query box are buttons controlling the ordering. This will be touched on momentarily. First a word about the Inherited buttons. Deselecting an inherited entity removes its member from display, but that's not the sum of it. There is valuable interaction with the query box to remember. For a member to show, it must satisfy the query box filter and be in an entity that is selected. Try this now:

• Remain on LinkedList.
• Enter ++ in the query box.
• Note the presence of the ++ method.
• Deselect TraversableLike.

++ is removed from view when TraversableLike is deselected.

The ordering options commonly seen are: Alphabetic, By Inheritance. There is another option that can be seen by navigating to the package documentation for scala.langauge, which is shown in Figure 8.10.

You can see two groups in use: Language Features and Experimental Language Features. These groups are defined by Scaladoc tags. You will be finding out how to define your own groups later.

Entity Member Details

A member can be a constructor, a method, a type, a type alias, or a value. The documentation provided for each member will be covered in depth when you learn how to add Scaladoc yourself. Here, an important aspect of the alphabetic member ordering is described. Knowing the logic behind the default ordering will allow you to benefit more deeply from any API documentation you study.

Take a look at the documentation for Set from the Standard Library. In Alphabetic mode the members are grouped under Instance Constructors, Type Members, Abstract Value Members, Concrete Value Members, and Shadowed Implicit Value Members. Within each group the members are ordered alphabetically. If you were looking at an entity with a member for each category you would see the groups from Table 8.1.

Group	Description
Instance Constructors	Primary and auxiliary constructors. Can included deprecated constructors.
Type Members	Type aliases, traits and classes. Can included deprecated members.
Abstract Value Members	Abstract methods and values. Can included deprecated members.
Value Members/Concrete Value Members	Concrete methods and values. Excludes shadowed implicit members and deprecated members. When the Abstract Value Members group is not empty this group is called Concrete Value Members; otherwise it is Values Members.
Shadowed Implicit Value Members	Shadowed or ambiguous implicits. Excludes any deprecated members.
Deprecated Value Members	Deprecated concrete value members.

The trait StringLike from the Standard Library uses five of the six alphabetic groups. See Figure 8.11.

Entity member information is included in this order: Instance Constructors, Type Members, Abstract Value Members, Value Members/Concrete Value Members, depending on presence of abstract value members, Shadowed Implicit Value Members, and Deprecated Value Members.

Formatting with Inline Wiki Syntax

Follow these steps to start your journey into the world of Scaladoc formatting. Start with some inline formatting examples.

If you would prefer not to enter the examples, but would still like to follow along, then you can use the source code present in the Git repo identified at the introduction section of the book.

Step 1: Create a class Galaxy in the same package as Universe,

package com.scalacraft.professionalscala.chapter8.cosmos

class Galaxy

Step 2: Add a class comment using each of the inline wiki syntax options:

/**
  * All inline styles: '''bold''', ''italic'', `monospace`, __underline__,
     ^superscript^, ,,subscript,,.
  */
class Galaxy

Step 3: Generate the Scaladoc from the command line, this time supplying a shell glob to identify all the source files in the current directory:

$ scaladoc -d output *.scala
model contains 8 documentable templates

Step 4: Load the Scaladoc for Galaxy in your browser and compare the outcome to Figure 8.13.

Table 8.2 details the syntax for inline styling.

Nesting Inline Styles

Inline styles can be nested in the majority of cases as shown in Figure 8.14. One notable exception is the failure to nest bold inside italic where an extraneous single quote escapes into the page.

If you are interested to learn the details of Scaladoc parsing, clone the Scala GitHub repo and look at CommentFactoryBase.

The source for nested formatting examples is available from the GitHub repo as misc-examples/InlineNesting.scala.

Structuring with Block Elements

Now that you have worked with inline formatting, you can move on to the block element, which occupies the next level of the Scaladoc food chain. Block elements allow you to structure your documentation in several ways to enhance the presentation at a higher level. Again, wiki syntax is used to facilitate this (see Table 8.3). In this section you will extend Galaxy to include examples of each of the five block elements that are listed here:

• Titles
• Paragraphs
• Code blocks
• Lists
• Horizontal rules

Step 1: Return to Galaxy and extend the Scaladoc comment to match this:

package com.scalacraft.professionalscala.chapter8.cosmos

/**
  * All inline styles: '''bold''', ''italic'', `monospace`, __underline__,
      ^superscript^, ,,subscript,,.
  *
  * =Title 1: Introduction=
  *
  * Paragraph: A galaxy is a system of stars, gas and dust.
  *
  * Create a galaxy using the `new` keyword,
  * {{{
  *   /* Code example */
  *   val zeta = new Galaxy
  * }}}
  *
  * ----
  *
  * ==Title 2: Types==
  *
  * There are different types of galaxy,
  *
  *  - Elliptical
  *    A. Maffei 1
  *    A. Centaurus A
  *  - Spiral
  *    1. M100
  *    1. NGC 1365
  *    - Barred Spiral
  *      I. NGC 1300
  *      I. NGC 1073
  *  - Irregular
  *    i. PGC 18431
  *    i. IC 559
  *  - Lenticular
  *    a. Messier 84
  *    a. Cartwheel Galaxy
  */
class Galaxy

Step 2: Generate the Scaladoc from the command line:

$ scaladoc -d output *.scala
model contains 8 documentable templates

Step 3: Load the Scaladoc for Galaxy in your browser and compare the outcome to Figure 8.15.

The wiki syntax options for lists deserves further explanation starting with whitespace indenting.

In the context of lists, wiki syntax whitespace is significant for lists. You should use two spaces per level. Examine the source for Galaxy and you will note there are two spaces between the asterisk and the hyphen that introduces the first item as shown here.

  *  - Elliptical

The subsequent indents also use two spaces. You can use other levels of indenting, but to avoid wasting time on a triviality, always use two spaces to indent lists.

Finally, lists can have unindexed or indexed items depending the choice of item prefix. Table 8.4 catalogs the available wiki syntax for list prefixes.

// @formatter:off
/**
 * My carefully formatted Scaladoc
 */

Linking

Scaladoc supports a compact wiki syntax for generating links. To include a link to a page anywhere on the web, you should enclose the link in square brackets followed by an optional label that the reader will see. The Scaladoc generated from the code below is shown in Figure 8.16.

/**
  * An external link: [[http://science.nasa.gov/astrophysics/]].
  *
  * An external link with a label:
    [[http://science.nasa.gov/astrophysics/ Astrophysics]].
  */
class ExternalLinks

You now have external links under your belt. Follow the next steps to learn how to link to objects, traits, classes, methods, specific overloads of methods, and types. These are known as entity links.

Step 1. Add the new class Starquake shown below. Make sure you use the correct package.

package com.scalacraft.professionalscala.chapter8.cosmos.phenom

import com.scalacraft.professionalscala.chapter8.cosmos.Magnetar
import Starquake.QuakeMagnitude

class Starquake(val magnitude: QuakeMagnitude)

object Starquake {
  /** The magnitude of a quake. */
  type QuakeMagnitude = Int
  def triggerStarquake(magnetar: Magnetar): Starquake = new Starquake(1)
}

Step 2. Add Magnetar in the package above with Scaladoc links to Starquake elements as shown here.

package com.scalacraft.professionalscala.chapter8.cosmos

/**
  * Magnetars are commonly found within a [[Galaxy]].
  *
  * Trigger a [[phenom.Starquake]] by calling
  * [[phenom.Starquake.triggerStarquake triggerStarquake on object Starquake]
  */
class Magnetar(galaxy: Option[Galaxy]

Step 3. Generate the Scaladoc and confirm that it appears as shown in Figure 8.17. Note, this time it is necessary to extend the scaladoc command arguments to include the new package phenom. Use this list of arguments for the remainder of this chapter unless otherwise advised.

$ scaladoc -d output *.scala phenom/*.scala

Test each link.

Step 4. Now imagine you have a requirement to allow the magnitude of the Starquake to be passed in. This results in a method overload. Add the new method on the Starquake object as shown here:

object Starquake {
  /** The magnitude of a quake. */
  type QuakeMagnitude = Int
  def triggerStarquake(magnetar: Magnetar): Starquake = new Starquake(1)
  def triggerStarquake(magnetar: Magnetar, magnitude: QuakeMagnitude): Starquake =
    new Starquake(magnitude)
}

Step 5. Generate the Scaladoc. You will encounter this warning:

Magnetar.scala:3: warning: The link target "phenom.Starquake.triggerStarquake" is
  ambiguous. Several members fit the target:
(magnetar: Magnetar, magnitude: QuakeMagnitude):
  Starquake in object Starquake [chosen
(magnetar: Magnetar): Starquake in object Starquake

The Scaladoc was created, but the method ambiguity is resolved using a strategy you were not consulted about.

Step 6. Fix this pernicious behavior by selecting the method overload precisely in Magnetar. Also add a link to the new method. See below for details.

/**
  * Magnetars are commonly found within a [[Galaxy]].
  *
  * Trigger a [[phenom.Starquake]] by calling
  * [[phenom.Starquake.triggerStarquake(magnetar:com.scalacraft.professionalscala
      .chapter8.cosmos.Magnetar)* triggerStarquake on object Starquake]] or
  * specifying the quake magnitude with
  * [[phenom.Starquake.triggerStarquake(magnetar:com.scalacraft.professionalscala
      .chapter8.cosmos.Magnetar,magnitude:com.scalacraft.professionalscala
         .chapter8
      .cosmos.phenom.Starquake.QuakeMagnitude)* triggerStarquake on object
        Starquake]
  */

Step 7. Generate the Scaladoc, confirm it resembles Figure 8.18, and check the links to the Starquake overloaded methods.

The Magnetars Scaladoc comment above requires some explanation. What is happening with those lengthy type references? You can use these rules to generate disambiguated links to your own overloaded methods,

• Take the method signature from the source and remove all spaces.
• Drop the result type.
• Add an asterisk.
• Convert the type to the fully qualified type, escaping periods with backslash.

A general theme with the syntax for links is that Scaladoc will make a best effort to find a target for a link which is convenient, but this helpfulness may have surprising outcomes. Test your Scaladoc in a browser.

You will find that this crib sheet (Table 8.5) will handle the majority of link types typically found within a Scaladoc corpus.

Scaladoc links can be tricky to get right. To help with this, an extensive set of examples is provided in the code download for this chapter. Find the examples in misc-examples/links.scala. These examples have been adapted from a test case in the Scala source code. The original can be found at https://github.com/scala/scala/blob/2.11.x/test/scaladoc/resources/links.scala.

Locating Scaladoc

So far you have been adding and modifying Scaladoc on the top level type for the most part. Where else can Scaladoc be placed? Although Scaladoc comments can be added anywhere whitespace is allowed, comments will generate documentation if placed at these locations:

• Before a class, trait, or object declaration
• Before a package object declaration
• Before a method, value, or variable declaration
• Before an alias or abstract type declaration

See https://wiki.scala-lang.org/display/SW/Syntax for a more detailed account of this.

Everyday Tagging

In this section you will add a class Star, apply relevant Scaladoc tags, and view the generated documentation. This will introduce you to the tags you will use most often in your day-to-day development activities.

Step 1. Add Star as shown here.

package com.scalacraft.professionalscala.chapter8.cosmos

/**
  * Luminous sphere of plasma held together by own gravity.
  * @see [[https://en.wikipedia.org/wiki/Plasma_(physics) Plasma (Wikipedia)]
  * @see Found in a [[Galaxy]
  * @author <Your Name Here>
  * @author [[https://github.com/janekdb Janek]
  * @version 13.8
  * @since 0.7
  * @todo Add `+(other: Star)` to model stellar collisions
  * @todo Add magnetic field
  * @constructor Construct a [[Star]] with the given radius
  * @param radius Initial star radius in metres
  */
class Star(var radius: Double) {

  /** @return The mass of this star in kg */
  def mass: Long = ???

  /**
    * Trigger stellar collapse.
    * @param delay Seconds to wait until collapse
    * @param blackhole If true skip white dwarf and neutron star stages
    * @throws IllegalArgumentException if `delay` is negative
    * @throws IllegalStateException if already a blackhole
    */
  def collapse(delay: Int, blackhole: Boolean): Unit = ???
}

Step 2. Generate the Scaladoc and review the output in a browser. Figure 8.19 shows the expected output. The search pane has been removed from the figure to save space.

Tags fall into four groups with respect to the requirements of what must follow the tag. The simplest type of tag is the standalone tag, which is exemplified by @documentable. A standalone tag is essentially a flag. It is present or absent. You will cover an example of a standalone tag later in the form of @documentable. The next type of tag is the content tag. @since is a content tag. This type of tag expects content in the form of free text following the tag name. The penultimate type of tag is the symbol tag. This tag has a name followed by a symbol and then descriptive text. @param is an example of a symbol tag. For @param tags the expected symbol is the name of a method parameter. The last type of tag is a structured tag, exemplified by @contentDiagram. This type of tag imposes a syntax on the text that follows, which allows the effect of the tag to be controlled at a detailed level.

Table 8.6 explains the purpose of each tag you have used so far. You can use this as a quick reference.

In terms of deciding where to place tags, assume Scaladoc follows the principle of least surprise. Combine this with a tight review cycle on the generated Scaladoc and you won't often be surprised.

Before you learn how to group methods and other entities using the @group family of tags, there are a few more everyday tags to check over. Return to Star and follow these steps.

Step 1. Add the freeze method to the end of the class as shown here.

/**
  * Use some freezers to freeze sunspots.
  * @example
  * {{{
  *   val star = …
  *   val freezers = List.fill(63)(new Icecube)
  *   val partiallySpentFreezers = star.freezeSunspots(freezers)
  * }}}
  * @note Do not call if collapsed
  * @note Following this the radius will be reduced
  * @tparam T A type that `freeze` can use to freeze a sunspot
  * @param freezers
  * @param freeze A function to freeze a sunspot on a star given a freezer
  * @return The freezers minus any used freezing capacity
  */
@deprecated("Use SolarKit instead", "14.0")
def freezeSunspots[T](freezers: List[T], freeze: (Star, T) => T): List[T] = ???

Step 2. Generate the Scaladoc and review the output in a browser. Figure 8.20 shows the expected output. Only the new method is shown to avoid repetition.

Notice the threefold impact of annotating with @deprecated. The method appears in the Deprecated Value Members section at the end of the page, the deprecation version and comment are shown, and as part of the generic handling of annotations, the annotation is listed in the Annotations section.

Table 8.7 explains the purpose of the newly introduced tags.

Member Permalinks

Go to any member and hover over the top right of the documentation. Right click and copy to get a deep link directly to the method. This is illustrated in Figure 8.21.

Tagging for Groups

Now you have mastered the common fare of Scaladoc tagging, so it is time to ascend to more rarefied strata. In this section you will create a class that demonstrates the use of Scaladoc groups that allow related members of an entity to be collected together.

Step 1. Add the class shown here to the project.

 package com.scalacraft.professionalscala.chapter8.cosmos

/**
  * Star Types with examples.
  *
  * @groupname Type-O Star Type 0
  * @groupdesc Type-O Blue, average solar mass: 60
  * @groupprio Type-O 10
  *
  * @groupname Type-B Star Type B
  * @groupdesc Type-B Blue, average solar mass: 18
  * @groupprio Type-B 20
  *
  * @groupname Type-K Star Type K
  * @groupdesc Type-K Orange to Red, average solar mass: 0.8
  * @groupprio Type-K 30
  */
trait StarTypes {

  /** @group Type-O */
  val `10 Lacertra`: Star

  /** @group Type-B */
  val Rigel: Star

  /** @group Type-B */
  val Spica: Star

  /** @group Type-K */
  val Arcturus: Star

  /** @group Type-K */
  val Aldebaran: Star
}

Step 2. Generate the Scaladoc and review the output in a browser. To take maximum advantage of the group tags the -groups option must be supplied. Without this, the Grouped button will be missing from the Ordered section.

$ scaladoc" -d output -groups *.scala phenom/*.scala

Figure 8.22 shows the expected output. You can see vals have been listed under the group descriptions corresponding to the given @group tag. Try switching between Grouped and Alphabetic.

Table 8.8 explains the purpose of the group tags.

Advanced Tagging

You have arrived at the advanced Scaladoc tags, some of which you will try out with a few more code additions. To start with you will see how to place a simplifying lens onto any method signature no matter how hieroglyphically rich it is, how to not repeat yourself, and how to elevate nested entities to first class citizens in the context of documentation. Following that, you will gain insight into tags that control documentation at a higher level.

“Seeing, hearing, feeling, are miracles, and each part and tag of me is a miracle.”

—“SONG OF MYSELF,” WALT WHITMAN

Follow these steps to get a feel for the possibilities of @define, @usecase, and @documentable.

Step 1. Add the code from the code listing below into Planet.scala. This is the Scaladoc before you fully augment it with the new tags. A macro expansion Body is defined in Terraformable and used in the @return tag. You will see the utility of this when you extend the Scaladoc with @inheritdoc.

package com.scalacraft.professionalscala.chapter8.cosmos

/**
  * @define Body Terraformable
  */
trait Terraformable[T] {

  /**
    * Create a terraformed copy of this $Body.
    * @param tfs A collection of [[Terraformer]]s to apply in order
    * @return A terraformed copy of this $Body
    */
  def terraform[P1 >: T, P2 <: T](implicit tfs: Seq[Terraformer[P1, P2]]): T
}

trait Terraformer[T, U] {
  def terraform[U <: T](body: T): U
}

class Planet extends Terraformable[Planet] {

  /**
    * A specialised kind of [[Planet]
    **/
  type SpecialisedPlanet <: Planet

  /**
    * Create a new world from this planet.
    * @note May result in mass extinction of existing life
    */
  def terraform[P1 >: Planet, SpecialisedPlanet
    (implicit tfs: Seq[Terraformer[P1, SpecialisedPlanet]]): Planet = ???
}

Step 2. Generate the Scaladoc and review the output in a browser. Figure 8.23 shows the expected output.

You should make note of the following aspects of the terraform method documentation before you add the new tags, an action that will change each of these points.

• The @return and @param tags are inherited from the Terraformable trait.
• The @return comment mentions Terraformable.
• The terraform method comment from Terraformable trait is missing.
• The SpecialisedPlanet type alias is not a hyperlink.
• The terraform method signature is very busy with implicits and type parameters—not great if you have an entire planetary system to get done.

Step 3. Edit Planet by adding a redefinition of the Body macro into the class comment, a @documentable tag on the type alias, and @inhertdoc on the terraform method as shown below.

/**
  * @define Body ''candidate'' colony world
  */
class Planet extends Terraformable[Planet] {

  /**
    * A specialised kind of [[Planet]
    * @documentable
    **/
  type SpecialisedPlanet <: Planet

  /**
    * @inheritdoc
    * Create a new world from this planet.
    * @note May result in mass extinction of existing life
    */
  def terraform[P1 >: Planet, SpecialisedPlanet
    (implicit tfs: Seq[Terraformer[P1, SpecialisedPlanet]]): Planet = ???
}

Step 4. Generate the Scaladoc. Figure 8.24 shows the expected documentation.

Now review the differences.

• The inherited @return comment now mentions “candidate colony world” instead of Terraformable.
• The terraform comment from Terraformable is now present beneath the comment defined in Planet. Remember, this was defined as “Create a terraformed copy of this $Body.” @inheritdoc contributed to this change.
• The effect of the redefinition of the Body macro can be seen in both the @return comment and the method comment.
• Macro definitions can contain wiki syntax.

The SpecialisedPlanet type alias is now a hyperlink.

Click SpecialisedPlanet to see that an entire page has been created as a consequence of placing @documentable tag on the type alias. The page header is shown in Figure 8.25.

Next, you will use @usecase to simplify the terraform method signature.

Edit Planet once more.

Step 1. Modify the comment on the terraform method as shown here.

/**
  * @inheritdoc
  * @usecase def terraform: Planet
  * Create a new world from this planet.
  * @inheritdoc
  * @note May result in mass extinction of existing life
  */
def terraform[P1 >: Planet, SpecialisedPlanet
  (implicit tfs: Seq[Terraformer[P1, SpecialisedPlanet]]): Planet = ???

Generate the Scaladoc. Figure 8.26 shows the new documentation of the terraform method.

The key differences are the introduction of the simplified method signature and the demotion of the full signature down into two collapsible sections. With details on demand your API documents will be simple to scan through while still providing the full signature for those sufficiently motivated to enquire more deeply.

To conclude this section you will briefly check out the diagramming related tags: @contentDiagram and @inheritanceDiagram. SVG-based inheritance and content diagrams are created by scaladoc when the -diagrams flag is supplied. You have two types of diagrams at your disposal:

• Content for showing contained entities
• Inheritance for showing inheritance relationships

Take a look at an example of a content diagram here: http://www.scala-lang.org/api/2.11.7/scala-reflect/index.html#scala.reflect.api.Symbols. The effects of using @contentDiagram in the main comment for Symbol are shown in Figure 8.27.

The diagram shows the type aliases contained in the Symbols trait. Here is an excerpt from Symbols corresponding to the types on display in Figure 8.27.

  type Symbol >: Null <: AnyRef with SymbolApi
  type TypeSymbol >: Null <: TypeSymbolApi with Symbol
  type TermSymbol >: Null <: TermSymbolApi with Symbol
  type MethodSymbol >: Null <: MethodSymbolApi with TermSymbol
  type ModuleSymbol >: Null <: ModuleSymbolApi with TermSymbol
  type ClassSymbol >: Null <: ClassSymbolApi with TypeSymbol

By default packages and objects will get content diagrams. For traits and classes you will need to add the tag.

Inheritance diagrams are generated by default for traits and classes, but when you require fine grained control of the inheritance diagrams, @inheritanceDiagram can be added to allow exclusionary specifiers to be added. These can be used to remove distracting elements for the diagram. As an example, suppose you wanted to omit superclasses from your diagrams. You can add hideSuperclasses to the tag as shown here to achieve that.

/**
* @inheritanceDiagram hideSuperclasses
*/
class ExampleClass extends Example2 with Example3

You can use these specifiers with @contentDiagrams as well. The specifiers you can use are:

• hideNodes
• hideDiagram
• hideOutgoingImplicits
• hideSubclasses
• hideEdges
• hideIncomingImplicits
• hideSuperclasses
• hideInheritedNodes

Consult the Scala source code for examples of how to use these options.

Table 8.9 summarizes the purpose of the advanced tags.

Configuring Maven

Provided you have already configured scala-maven-plugin, you can generate the Scaladoc via a Maven goal. Execute this code and then browse to target/site/scaladocs/index.html:

$ mvn scala:doc

If you need to elevate the structure around your build process, then adding a suitable plugin configuration will trigger Scaladoc generation during the Maven site phase. Take the configuration in the code below and add this into the project/build/plugins elements alongside the scala-maven-plugin configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.4</version>
    <configuration>
        <reportPlugins>
            <plugin>
                <artifactId>maven-project-info-reports-plugin</artifactId>
                <version>2.8.1</version>
            </plugin>
            <plugin>
                <groupId>net.alchim31.maven</groupId>
                <artifactId>scala-maven-plugin</artifactId>
                <version>3.2.2</version>
                <configuration>
                    <jvmArgs>
                        <jvmArg>-Xms64m</jvmArg>
                        <jvmArg>-Xmx1024m</jvmArg>
                    </jvmArgs>
                    <args>
                        <arg>-doc-footer</arg>
                        <arg>${copyright}</arg>
                        <arg>-groups</arg>
                        <arg>-doc-title</arg>
                        <arg>Cosmic Toolkit</arg>
                    </args>
                </configuration>
            </plugin>
        </reportPlugins>
    </configuration>
</plugin>

Now you can generate your Scaladoc with Maven, either from within the comfort of your IDE, or on the CLI as shown here.

$ mvn site

As before, the root page is located at target/site/scaladocs/index.html. The site goal will also generate additional project documentation unrelated to Scaladoc.

Configuring SBT

SBT supports a doc task that generates Scaladoc from your source files. If you are new to SBT, review the SBT chapter and an introduction to SBT in general. For now it's enough to add the minimal project file shown here to the module root level (chapter-8/):

lazy val root = (project in file(".")).
  settings(
    name := "Cosmic Toolkit",
    version := "0.1.0-SNAPSHOT",
    scalaVersion := "2.11.7"
  )

val copyright = "Janek Bogucki 2015"
scalacOptions in (Compile,doc) ++=
  Seq("-doc-footer", copyright, "-groups", "-doc-title", "Cosmic Toolkit")

With that in place, call the doc task from SBT:

$ sbt doc

This will generate the same Scaladoc as the Maven configuration.