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.”

Back to top

Problem

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

Back to top

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 com.acme.foo

/**
  * 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 [[http://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.

Back to top

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

Back to top

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.

Back to top

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
Back to top

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.

Back to top

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.

Back to top

See Also

Back to top

The Scala Cookbook

This tutorial is sponsored by the Scala Cookbook, which I wrote for O’Reilly:

You can find the Scala Cookbook at these locations:

Back to top

Add new comment

The content of this field is kept private and will not be shown publicly.

Anonymous format

  • Allowed HTML tags: <em> <strong> <cite> <code> <ul type> <ol start type> <li> <pre>
  • Lines and paragraphs break automatically.
By submitting this form, you accept the Mollom privacy policy.