为所有包、类、特征、方法和其他成员提供文档非常重要。Scaladoc 通常遵循 Javadoc 的惯例，但提供了许多其他功能，简化了为 Scala 代码编写文档的过程。
通常，您更关心内容和写作风格，而不是格式。Scaladoc 既对代码的新手用户也有用，对有经验的用户也有用。实现这一点非常简单：在您编写时增加详细程度和解释，从简洁的摘要开始（对有经验的用户来说很有用，作为参考），同时在详细部分提供更深入的示例（有经验的用户可以忽略这些示例，但对新手来说可能非常宝贵）。
Scaladoc 工具不要求文档注释样式。
以下示例演示了单行摘要，后跟详细文档，采用三种常见的缩进样式。
Javadoc 样式
/**
* Provides a service as described.
*
* This is further documentation of what we're documenting.
* Here are more details about how it works and what it does.
*/
def member: Unit = ()
Scaladoc 样式，其中缩进星号在第二列对齐
/** Provides a service as described.
*
* This is further documentation of what we're documenting.
* Here are more details about how it works and what it does.
*/
def member: Unit = ()
Scaladoc 样式，其中注释星号对齐在第三列
/** Provides a service as described.
*
* This is further documentation of what we're documenting.
* Here are more details about how it works and what it does.
*/
def member: Unit = ()
由于注释标记对空格敏感，因此该工具必须能够推断左边界。
如果只需要简单、简短的描述，可以使用单行格式
/** Does something very simple */
def simple: Unit = ()
请注意，与 Javadoc 约定相反，Scaladoc 样式中的文本从注释的第一行开始。此格式可以节省源文件中的垂直空间。
在任一 Scaladoc 样式中，所有文本行都对齐在第五列。由于 Scala 源通常缩进两个空格，因此文本以视觉上令人愉悦的方式与源缩进对齐。
有关 Scaladoc 格式化的更多技术信息，请参阅 面向库作者的 Scaladoc。
通用样式
保持 Scaladoc 的一致样式非常重要。同样重要的是，Scaladoc 既要面向不熟悉你的代码的人，也要面向只需要快速参考的经验丰富的用户。以下是一些通用准则
- 尽可能快地切入正题。例如，说“如果某个条件为真，则返回真”，而不是“如果某个条件返回真”。
- 尝试将方法的第一句格式化为“返回 XXX”，例如“返回列表的第一个元素”，而不是“此方法返回”或“获取第一个”等。方法通常会返回内容。
- 类也是如此；省略“此类执行 XXX”；只需说“执行 XXX”
- 使用方括号语法创建指向引用的 Scala 库类的链接，例如
[[scala.Option]] - 在
@return注释中总结方法的返回值，为 Scaladoc 主体保留更长的描述。 - 如果方法的文档是对该方法返回内容的一行描述，请不要使用
@return注释重复它。 - 记录方法实际执行的内容，而不是方法应该执行的内容。换句话说，说“返回将 f 应用于 x 的结果”，而不是“返回将 f 应用于 x 的结果”。虽然微妙，但很重要。
- 在引用类的实例时，使用“this XXX”或“this”，而不是“the XXX”。对于对象，说“this object”。
- 使代码示例与本指南保持一致。
- 尽可能使用 wiki 样式语法，而不是 HTML。
- 示例应使用完整的代码清单或 REPL，具体取决于需要什么（包含 REPL 代码的最简单方法是在 REPL 中开发示例并将其粘贴到 Scaladoc 中）。
- 自由使用
@macro来引用需要特殊格式的常用重复值。
包
为每个包提供 Scaladoc。这将放在包目录中名为 package.scala 的文件中，如下所示（对于包 parent.package.name.mypackage）
package parent.package.name
/** This is the Scaladoc for the package. */
package object mypackage {
}
程序包文档首先应记录程序包中包含哪些类型的类。其次，记录程序包对象本身提供的通用类型。
虽然程序包文档不必是有关如何使用程序包中类的完整教程，但它应提供主要类的概述，并提供一些有关如何使用该程序包中类的基本示例。务必使用方括号符号引用类
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 {}
类、对象和特征
记录所有类、对象和特征。Scaladoc 的第一句话应提供类或特征的作用的摘要。使用 @tparam 记录所有类型参数。
类
如果应使用伴随对象创建类，请在类描述后注明（但将构造的详细信息留给伴随对象）。遗憾的是，目前无法内联创建到伴随对象的链接，但生成的 Scaladoc 会在类文档输出中为您创建链接。
如果应使用构造函数创建类，请使用 @constructor 语法记录它
/** 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) {
}
根据类的复杂性，提供常见用法示例。
对象
由于对象可用于各种目的，因此记录如何使用对象（例如，作为工厂、用于隐式方法）非常重要。如果此对象是其他对象的工厂，请在此处注明，将具体信息推迟到 apply 方法的 Scaladoc。如果您的对象不使用 apply 作为工厂方法，请务必注明实际方法名称
/** 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) = {}
}
如果您的对象包含隐式转换，请在 Scaladoc 中提供示例
/** Implicit conversions and helpers for [[mypackage.Complex]] instances.
*
* {{{
* import ComplexImplicits._
* val c: Complex = 4 + 3.i
* }}}
*/
object ComplexImplicits {}
特征
概述特征的作用后，概述在混合特征的类中必须指定的方法和类型。如果有已知的类使用该特征，请引用它们。
方法和其他成员
记录所有方法。与其他可记录实体一样，第一句话应是方法作用的摘要。后续句子会进一步详细说明。记录每个参数以及每个类型参数（使用 @tparam）。对于柯里化函数，请考虑提供有关预期或惯用用法更详细的示例。对于隐式参数，请特别注意说明这些参数的来源以及用户是否需要执行任何额外工作以确保参数可用。