It is important to provide documentation for all packages, classes, traits, methods, and other members. ScalaDoc generally follows the conventions of Javadoc, however there are many additional features to make writing scaladoc simpler.
In general, you want to worry more about substance and writing style than in formatting. ScalaDocs need to be useful to new users of the code as well as experienced users. Achieving this is very simple: increase the level of detail and explanation as you write, starting from a terse summary (useful for experienced users as reference), while providing deeper examples in the detailed sections (which can be ignored by experienced users, but can be invaluable for newcomers).
The general format for a ScalaDoc comment should be as follows:
Documentation/** This is a brief description of what's being documented.
*
* This is further documentation of what we're documenting. It should
* provide more details as to how this works and what it does.
*/
def myMethod = {}
For methods and other type members where the only documentation needed is a simple, short description, this format can be used:
/** Does something very simple */
def simple = {}
Note, especially for those coming from Java, that the left-hand margin of asterisks falls under the _third_ column, not the second, as is customary in Java.
See the AuthorDocs on the Scala wiki for more technical info on formatting ScalaDoc.
It is important to maintain a consistent style with ScalaDoc. It is also important to target ScalaDoc to both those unfamiliar with your code and experienced users who just need a quick reference. Here are some general guidelines:
[[scala.Option]]@return annotation,
leaving a longer description for the main ScalaDoc.@return annotation.@macro to refer to commonly-repeated values
that require special formatting.Provide ScalaDoc for each package. This goes in a file named
package.scala in your package’s directory and looks like so (for the
package parent.package.name.mypackage):
package parent.package.name
/** This is the ScalaDoc for the package. */
package object mypackage {
}
A package’s documentation should first document what sorts of classes are part of the package. Secondly, document the general sorts of things the package object itself provides.
While package documentation doesn’t need to be a full-blown tutorial on using the classes in the package, it should provide an overview of the major classes, with some basic examples of how to use the classes in that package. Be sure to reference classes using the square-bracket notation:
package my.package
/** Provides classes for dealing with complex numbers. Also provides
* implicits for converting to and from `Int`.
*
* ==Overview==
* The main class to use is [[my.package.complex.Complex]], as so
* {{{
* scala> val complex = Complex(4,3)
* complex: my.package.complex.Complex = 4 + 3i
* }}}
*
* If you include [[my.package.complex.ComplexConversions]], you can
* convert numbers more directly
* {{{
* scala> import my.package.complex.ComplexConversions._
* scala> val complex = 4 + 3.i
* complex: my.package.complex.Complex = 4 + 3i
* }}}
*/
package complex {}
Document all classes, objects, and traits. The first sentence of the
ScalaDoc should provide a summary of what the class or trait does.
Document all type parameters with @tparam.
If a class should be created using it’s companion object, indicate as such after the description of the class (though leave the details of construction to the companion object). Unfortunately, there is currently no way to create a link to the companion object inline, however the generated ScalaDoc will create a link for you in the class documentation output.
If the class should be created using a constructor, document it using
the @constructor syntax:
/** A person who uses our application.
*
* @constructor create a new person with a name and age.
* @param name the person's name
* @param age the person's age in years
*/
class Person(name: String, age: Int) {
}
Depending on the complexity of your class, provide an example of common usage.
Since objects can be used for a variety of purposes, it is important to
document how to use the object (e.g. as a factory, for implicit
methods). If this object is a factory for other objects, indicate as
such here, deferring the specifics to the ScalaDoc for the apply
method(s). If your object doesn’t use apply as a factory method, be
sure to indicate the actual method names:
/** Factory for [[mypackage.Person]] instances. */
object Person {
/** Creates a person with a given name and age.
*
* @param name their name
* @param age the age of the person to create
*/
def apply(name: String, age: Int) = {}
/** Creates a person with a given name and birthdate
*
* @param name their name
* @param birthDate the person's birthdate
* @return a new Person instance with the age determined by the
* birthdate and current date.
*/
def apply(name: String, birthDate: java.util.Date) = {}
}
If your object holds implicit conversions, provide an example in the ScalaDoc:
/** Implicit conversions and helpers for [[mypackage.Complex]] instances.
*
* {{{
* import ComplexImplicits._
* val c: Complex = 4 + 3.i
* }}}
*/
object ComplexImplicits {}
After the overview of what the trait does, provide an overview of the methods and types that must be specified in classes that mix in the trait. If there are known classes using the trait, reference them.
Document all methods. As with other documentable entities, the first
sentence should be a summary of what the method does. Subsequent
sentences explain in further detail. Document each parameter as well as
each type parameter (with @tparam). For curried functions, consider
providing more detailed examples regarding the expected or idiomatic
usage. For implicit parameters, take special care to explain where
these parameters will come from and if the user needs to do any extra
work to make sure the parameters will be available.
Copyright © 2011-2013 EPFL. All rights reserved.
