Scala Cookbook

14.8. Generating Documentation with scaladoc

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