It is important to provide documentation for all packages, classes,traits, methods, and other members. Scaladoc generally follows theconventions of Javadoc, but provides many additional features thatsimplify writing documentation for Scala code.

In general, you want to worry more about substance and writing stylethan about formatting. Scaladocs need to be useful to new users of the codeas well as experienced users. Achieving this is very simple: increasethe level of detail and explanation as you write, starting from a tersesummary (useful for experienced users as reference), while providingdeeper examples in the detailed sections (which can be ignored byexperienced users, but can be invaluable for newcomers).

The Scaladoc tool does not mandate a documentation comment style.

The following examples demonstrate a single line summary followedby detailed documentation, in the three common styles of indentation.

Javadoc style:

  1. /**
  2.  * Provides a service as described.
  3.  *
  4.  * This is further documentation of what we're documenting.
  5.  * Here are more details about how it works and what it does.
  6.  */
  7. def member: Unit = ()

Scaladoc style, with gutter asterisks aligned in column two:

  1. /** Provides a service as described.
  2.  *
  3.  *  This is further documentation of what we're documenting.
  4.  *  Here are more details about how it works and what it does.
  5.  */
  6. def member: Unit = ()

Scaladoc style, with gutter asterisks aligned in column three:

  1. /** Provides a service as described.
  2.   *
  3.   * This is further documentation of what we're documenting.
  4.   * Here are more details about how it works and what it does.
  5.   */
  6. def member: Unit = ()

Because the comment markup is sensitive to whitespace,the tool must be able to infer the left margin.

When only a simple, short description is needed, a one-line format can be used:

  1. /** Does something very simple */
  2. def simple: Unit = ()

Note that, in contrast to the Javadoc convention, the text inthe Scaladoc styles begins on the first line of the comment.This format saves vertical space in the source file.

In either Scaladoc style, all lines of text are aligned on column five.Since Scala source is usually indented by two spaces,the text aligns with source indentation in a way that is visually pleasing.

SeeScaladoc for Library Authorsfor more technical info on formatting Scaladoc.

General Style

It is important to maintain a consistent style with Scaladoc. It is alsoimportant to target Scaladoc to both those unfamiliar with your code andexperienced users who just need a quick reference. Here are some generalguidelines:

  • Get to the point as quickly as possible. For example, say “returnstrue if some condition” instead of “if some condition return true”.
  • Try to format the first sentence of a method as “Returns XXX”, as in“Returns the first element of the List”, as opposed to “this methodreturns” or “get the first” etc. Methods typically returnthings.
  • This same goes for classes; omit “This class does XXX”; just say“Does XXX”
  • Create links to referenced Scala Library classes using thesquare-bracket syntax, e.g. [[scala.Option]]
  • Summarize a method’s return value in the @return annotation,leaving a longer description for the main Scaladoc.
  • If the documentation of a method is a one line description of whatthat method returns, do not repeat it with an @return annotation.
  • Document what the method does do not what the method should do.In other words, say “returns the result of applying f to x” ratherthan “return the result of applying f to x”. Subtle, but important.
  • When referring to the instance of the class, use “this XXX”, or“this” and not “the XXX”. For objects, say “this object”.
  • Make code examples consistent with this guide.
  • Use the wiki-style syntax instead of HTML wherever possible.
  • Examples should use either full code listings or the REPL, dependingon what is needed (the simplest way to include REPL code is todevelop the examples in the REPL and paste it into the Scaladoc).
  • Make liberal use of @macro to refer to commonly-repeated valuesthat require special formatting.

Packages

Provide Scaladoc for each package. This goes in a file namedpackage.scala in your package’s directory and looks like so (for thepackage parent.package.name.mypackage):

  1. package parent.package.name
  3. /** This is the Scaladoc for the package. */
  4. package object mypackage {
  5. }

A package’s documentation should first document what sorts of classesare part of the package. Secondly, document the general sorts of thingsthe package object itself provides.

While package documentation doesn’t need to be a full-blown tutorial onusing the classes in the package, it should provide an overview of themajor classes, with some basic examples of how to use the classes inthat package. Be sure to reference classes using the square-bracketnotation:

  1. package my.package
  2. /** Provides classes for dealing with complex numbers.  Also provides
  3.  *  implicits for converting to and from `Int`.
  4.  *
  5.  *  ==Overview==
  6.  *  The main class to use is [[my.package.complex.Complex]], as so
  7.  *  {{{
  8.  *  scala> val complex = Complex(4,3)
  9.  *  complex: my.package.complex.Complex = 4 + 3i
  10.  *  }}}
  11.  *
  12.  *  If you include [[my.package.complex.ComplexConversions]], you can
  13.  *  convert numbers more directly
  14.  *  {{{
  15.  *  scala> import my.package.complex.ComplexConversions._
  16.  *  scala> val complex = 4 + 3.i
  17.  *  complex: my.package.complex.Complex = 4 + 3i
  18.  *  }}}
  19.  */
  20. package complex {}

Classes, Objects, and Traits

Document all classes, objects, and traits. The first sentence of theScaladoc should provide a summary of what the class or trait does.Document all type parameters with @tparam.

Classes

If a class should be created using its companion object, indicate assuch after the description of the class (though leave the details ofconstruction to the companion object). Unfortunately, there is currentlyno way to create a link to the companion object inline, however thegenerated Scaladoc will create a link for you in the class documentationoutput.

If the class should be created using a constructor, document it usingthe @constructor syntax:

  1. /** A person who uses our application.
  2.  *
  3.  *  @constructor create a new person with a name and age.
  4.  *  @param name the person's name
  5.  *  @param age the person's age in years
  6.  */
  7. class Person(name: String, age: Int) {
  8. }

Depending on the complexity of your class, provide an example of commonusage.

Objects

Since objects can be used for a variety of purposes, it is important todocument how to use the object (e.g. as a factory, for implicitmethods). If this object is a factory for other objects, indicate assuch here, deferring the specifics to the Scaladoc for the applymethod(s). If your object doesn’t use apply as a factory method, besure to indicate the actual method names:

  1. /** Factory for [[mypackage.Person]] instances. */
  2. object Person {
  3.   /** Creates a person with a given name and age.
  4.    *
  5.    *  @param name their name
  6.    *  @param age the age of the person to create
  7.    */
  8.   def apply(name: String, age: Int) = {}
  10.   /** Creates a person with a given name and birthdate
  11.    *
  12.    *  @param name their name
  13.    *  @param birthDate the person's birthdate
  14.    *  @return a new Person instance with the age determined by the
  15.    *          birthdate and current date.
  16.    */
  17.   def apply(name: String, birthDate: java.util.Date) = {}
  18. }

If your object holds implicit conversions, provide an example in theScaladoc:

  1. /** Implicit conversions and helpers for [[mypackage.Complex]] instances.
  2.  *
  3.  *  {{{
  4.  *  import ComplexImplicits._
  5.  *  val c: Complex = 4 + 3.i
  6.  *  }}}
  7.  */
  8. object ComplexImplicits {}

Traits

After the overview of what the trait does, provide an overview of themethods and types that must be specified in classes that mix in thetrait. If there are known classes using the trait, reference them.

Methods and Other Members

Document all methods. As with other documentable entities, the firstsentence should be a summary of what the method does. Subsequentsentences explain in further detail. Document each parameter as well aseach type parameter (with @tparam). For curried functions, considerproviding more detailed examples regarding the expected or idiomaticusage. For implicit parameters, take special care to explain wherethese parameters will come from and if the user needs to do any extrawork to make sure the parameters will be available.