Scaladoc is a documentation system that lives in the comments of Scala source code and is related to the code structure within which it is written. It is based on other comment based documentation systems like Javadoc, but with some extensions such as:
Scaladoc comments go before the items they pertain to in a special comment block
that starts with a
/** and ends with a
*/, like this:
/** Start the comment here * and use the left star followed by a * white space on every line. * * Even on empty paragraph-break lines. * * Note that the * on each line is aligned * with the second * in /** so that the * left margin is on the same column on the * first line and on subsequent ones. * * The closing Scaladoc tag goes on its own, * separate line. E.g. * * Calculate the square of the given number * * @param d the Double to square * @return the result of squaring d */ def square(d: Double): Double = d * d
In the example above, this Scaladoc comment is associated with the method
square since it is right before it in the source code.
Scaladoc comments can go before fields, methods, classes, traits, objects and even (especially) package objects. Scaladoc comments for package objects make a great place to put an overview of a specific package or API.
For class primary constructors which in Scala coincide with the definition
of the class itself, a
@constructor tag is used to target a comment to be
put on the primary constructor documentation rather than the class overview.
@ tags to provide specific detail fields in the comments. These
@constructorplaced in the class comment will describe the primary constructor.
@returndetail the return value from a method (one per method).
@throwswhat exceptions (if any) the method or constructor may throw.
@paramdetail a value parameter for a method or constructor, provide one per parameter to the method/constructor.
@tparamdetail a type parameter for a method, constructor or class. Provide one per type parameter.
@seereference other sources of information like external document links or related entities in the documentation.
@noteadd a note for pre or post conditions, or any other notable restrictions or expectations.
@examplefor providing example code or related example documentation.
@usecaseprovide a simplified method definition for when the full method definition is too complex or noisy. An example is (in the collections API), providing documentation for methods that omit the implicit
@group <group>- mark the entity as a member of the
@groupname <group> <name>- provide an optional name for the group.
<name>is displayed as the group header
@groupdesc <group> <description>- add optional descriptive text to display under the group name. Supports multiline formatted text.
@contentDiagram- use with traits and classes to include a content hierarchy diagram showing included types. The diagram content can be fine tuned with additional specifiers taken from
hideDiagramcan be supplied to prevent a diagram from being created if it would be created by default. Packages and objects have content diagrams by default.
@authorprovide author information for the following entity
@versionthe version of the system or API that this entity is a part of.
@versionbut defines the system or API that this entity was first defined in.
@todofor documenting unimplemented features or unimplemented aspects of an entity.
@deprecatedmarks the entity as deprecated, providing both the replacement implementation that should be used and the version/date at which this entity was deprecated.
@migrationlike deprecated but provides advanced warning of planned changes ahead of deprecation. Same fields as
@inheritdoctake comments from a superclass as defaults if comments are not provided locally.
@documentableExpand a type alias and abstract type into a full template page. - TODO: Test the “abstract type” claim - no examples of this in the Scala code base
@define <name> <definition>allows use of
$namein other Scaladoc comments within the same source file which will be expanded to the contents of
If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used.
@return and other entity tags are omitted
but available from a superclass, those comments will be used.
For explicit comment inheritance, use the
It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead.
Some of the standard markup available:
`monospace` ''italic text'' '''bold text''' __underline__ ^superscript^ ,,subscript,, [[entity link]], e.g. [[scala.collection.Seq]] [[http://external.link External Link]], e.g. [[http://scala-lang.org Scala Language Site]]
*in the margin for the comment is valid (and should be included) but the line should be blank otherwise.
}}}and may be multi-line. Indentation is relative to the starting
*for the comment.
=characters, with more
=denoting subheadings. E.g.
-, while numbered lists can be denoted using
a.for the various numbering styles.
returns Xrather than
this method returns X, and
does X,Y & Zrather than
this method does X, Y and Z.
@returntag and other forms of repetitive commenting.