How to generate Scala documentation with the ‘scaladoc’ command

This is an excerpt from the Scala Cookbook. This is Recipe 14.8, “How to generate Scala documentation with the scaladoc command.”

Problem

You’ve annotated your Scala code with Scaladoc, and you want to generate developer documentation for your API.

Solution

To generate Scaladoc API documentation, document your code using Scaladoc tags, and then create the documentation using an SBT task or the scaladoc command. You can mark up your source code using Scaladoc tags as well as a wiki-like syntax. The following code shows many of the Scaladoc tags and a few of the wiki-style markup tags:

package co.kbhr.scaladoc_tags

/**
  * A class to represent a ''human being''.
  *
  * Specify the `name`, `age`, and `weight` when creating a new `Person`,
  * then access the fields like this:

  * {{{
  * val p = Person("Al", 42, 200.0)
  * p.name
  * p.age
  * p.weight
  * }}}
  *
  * Did you know: The [[com.acme.foo.Employee]] extends this class.
  *
  * @constructor Create a new person with a `name`, `age`, and `weight`.
  * @param name The person's name.
  * @param age The person's age.
  * @param weight The person's weight.
  * @author Alvin Alexander
  * @version 1.0
  * @todo Add more functionality.
  * @see See [[https://alvinalexander.com alvinalexander.com]] for more "
  * information.
  */
@deprecated("The `weight` field is going away", "1.0")
class Person (var name: String, var age: Int, var weight: Double) {

  /**
   * @constructor This is an auxiliary constructor. Just need a `name` here.
   */
  def this(name: String) {
    this(name, 0, 0.0)
  }

  /**
   * @return Returns a greeting based on the `name` field.
   */
  def greet = s"Hello, my name is $name"
}

/**
  * @constructor Create a new `Employee` by specifying their `name`, `age`, "
  * and `role`.
  * @param name The employee's name.
  * @param age The employee's age.
  * @param role The employee's role in the organization.
  * @example val e = Employee("Al", 42, "Developer")
  */
class Employee(name: String, age: Int, role: String) extends Person(name, age, 0) "
{

  /**
   * @throws boom Throws an Exception 100% of the time, be careful.
   */
  @throws(classOf[Exception])
  def boom { throw new Exception("boom") }

  /**
   * @return Returns a greeting based on the `other` and `name` fields.
   * @param other The name of the person we're greeting.
   */
  override def greet(other: String) = s"Hello $other, my name is $name"
}

With this code saved to a file named Person.scala, generate the Scaladoc documentation with the scaladoc command:

$ scaladoc Person.scala

This generates a root index.html file and other related files for your API documentation. Similarly, if you’re using SBT, generate Scaladoc API documentation by running the sbt doc command in the root directory of your project:

$ sbt doc

This generates the same API documentation, and places it under the target directory of your SBT project. With Scala 2.10 and SBT 0.12.3, the root file is located at target/scala-2.10/api/index.html.

Sample Scaladoc output

Figure 14-3 shows the resulting Scaladoc for the Person class, and Figure 14-4 shows the Scaladoc for the Employee class. Notice how the Scaladoc and wiki tags affect the documentation.

Figure 14-3. The Scaladoc for the Person class

Figure 14-4. The Scaladoc for the Employee` class

Common Scaladoc tags

Most Scaladoc tags are similar to Javadoc tags. Common Scaladoc tags are shown in Table 14-1.

Table 14-1. Common Scaladoc tags

Tag	Description	Number allowed
@author	The author of the class.	Multiple tags are allowed.
@constructor	Documentation you want to provide for the constructor.	One (does not currently work on auxiliary constructors)
@example	Provide an example of how to use a method or constructor.	Multiple
@note	Document pre- and post-conditions, and other requirements.	Multiple
@param	Document a method or constructor parameter.	One per parameter
@return	Document the return value of a method.	One
@see	Describe other sources of related information.	Multiple
@since	Used to indicate that a member has been available since a certain version release.	One
@todo	Document “to do” items for a method or class.	Multiple
@throws	Document an exception type that can be thrown by a method or constructor.	Multiple
@version	The version of a class.	One

These are just some of the common tags. Other tags include @define, @migration, @tparam, and @usecase. Other Scala annotation tags like @deprecated and @throws also result in output to your documentation.

Scaladoc “wiki” character formatting tags

As shown in the source code, you can format your documentation using wiki-like tags. Table 14-2 shows the most common wiki character formatting tags, and Table 14-3 shows the most common wiki paragraph formatting tags.

Table 14-2. Scaladoc wiki character formatting tags

Format	Tag example
Bold	'''foo'''
Italic	''foo''
Monospace (fixed-width)	foo
Subscript	,,foo,,
Superscript	^foo^
Underline	foo

Scaladoc “wiki” paragraph formatting tags

Table 14-3. Scaladoc wiki paragraph formatting tags

Format	Tag example
Headings	=heading1= ==heading2== ===heading3===
New paragraph	A blank line starts a new paragraph
Source code block	// all on one line {{{ if (foo) bar else baz }}} // multiple lines {{{ val p = Person("Al", 42) p.name p.age }}}

Table 14-4 shows how to create hyperlinks in Scaladoc.

Table 14-4. Scaladoc hyperlink tags

Link type	Tag example
Link to a Scala type	[[scala.collection.immutable.List]]
Link to an external web page	[[http://alvinalexander.com My website]]

The Scaladoc tags and annotations are described in more detail in the Scala wiki, as well as the Wiki markup tags.

Generating Scaladoc documentation with SBT

SBT has several commands that can be used to generate project documentation. See Recipe 18.8, “Generating Project API Documentation” for a tabular listing of those commands.

See Also

• Recipe 5.8, “Declaring That a Scala Method Can Throw an Exception” and Recipe 17.2, “Add Exception Annotations to Scala Methods to Work with Java” for demonstrations of the @throws annotation
• Scaladoc wiki-like syntax
• Scaladoc tags
• The Scaladoc page in the Scala Style Guide
• Recipe 18.8, “Generating Project API Documentation” for details on generating Scaladoc documentation with SBT