Scaladoc syntax examples (Scaladoc tags, wiki markup)

In this article I share some examples of Scala’s Scaladoc syntax, including common Scaladoc tags, and the wiki-style of markup that Scaladoc supports.

An example of Scaladoc tags and wiki formatting

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

This figure shows the resulting Scaladoc for the Person class:

(Please note that this figure may be slightly different than the source code because I changed the source code over time.)

This figure shows the Scaladoc for the Employee class. Notice how the Scaladoc and wiki tags affect the documentation:

Common tags

Most Scaladoc tags are similar to Javadoc tags. Common Scaladoc tags are shown in the table below:

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. This table shows the most common 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

This table shows the most common 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 }}}

This table shows how to create hyperlinks in Scaladoc:

Link type	Tag example
Link to a Scala type	[[scala.collection.immutable.List]]
Link to an external web page	[[https://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 of the Scala Cookbook, “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 (this page no longer exists)
• Scaladoc for library authors
• 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