[scala代码风格指南]--Scaladoc

英文原文：http://docs.scala-lang.org/style/

译文如下：

Scaladoc

为所有包，类，特征，方法和其他成员提供文档很重要。Scaladoc通常遵循Javadoc的约定，但是还有许多其他功能可以使编写scaladoc更简单。

一般来说，您想要更多地关注实体和写作风格，而不是格式化。Scaladoc需要对代码的新用户以及经验丰富的用户有用。实现这一点非常简单：从简洁的总结（从有经验的用户作为参考）开始，增加细节和解释的水平，同时在详细的部分提供更深入的例子（有经验的用户可以忽略它，但可以对新来者来说是非常宝贵的）。

Scaladoc评论的一般格式应该如下：

/** 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 = {}

另一个Scaladoc注释样式在第三列中对齐第二个星号下的星号列。Scaladoc工具还接受Javadoc注释格式，文本位于单个星号之后，由单个空格分隔。由于注释标记对空格敏感，所以该工具必须能够推断左边距。

对于所需的唯一文档的方法和其他类型的成员是一个简单的简短描述，可以使用单行格式：

/** Does something very simple */
def simple = {}

请注意，与Javadoc约定相反，文本从注释的第一行开始，但后续文本保持对齐。特别是，文本对齐在两列的倍数上，因为Scala源通常缩进两列。

见 AuthorDocs 在斯卡拉维基上的格式Scaladoc更多的技术信息。

一、一般风格

与Scaladoc保持一致的风格是很重要的。将Scaladoc定位到不熟悉您的代码的用户以及只需要快速参考的经验丰富的用户也很重要。以下是一般的指导方针：

• 尽快到达这一点。例如，说“如果有些条件返回true”而不是“if some condition return true”。
• 尝试将方法的第一个句子格式化为“返回XXX”，如“返回列表的第一个元素”，而不是“此方法返回”或“获取第一个”等。方法通常返回的 东西。
• 这同样适用于课堂; 省略“这个班XXX”; 只要说“XXX”
• 使用方括号语法创建引用Scala Library类的链接，例如 [[scala.Option]]
• 在@return注释中总结方法的返回值，为主Scaladoc留下更长的描述。
• 如果方法的文档是该方法返回的一行描述，请不要用@return注释重复。
• 手册中有什么方法确实做的方法不是应该做的。换句话说，说“将f应用到x的结果”，而不是“将f应用到x的结果”。微妙但重要。
• 当提到课程的实例时，请使用“本XXX”或“此”而不是“XXX”。对于对象，说“这个对象”。
• 使代码示例与本指南一致。
• 尽可能使用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 {}

(三)性状

概述了特征的作用之后，提供一些必须在混合特征的类中指定的方法和类型的概述。如果有已知的类使用trait，请参考它们。

三、方法和其他成员

记录所有方法。与其他可记录实体一样，第一句应该是该方法执行的总结。后续句子进一步详细解释。记录每个参数以及每个类型参数（带@tparam）。对于咖喱功能，请考虑提供有关预期或习惯用法的更详细的示例。对于隐式参数，请特别注意说明这些参数来自哪里，以及用户是否需要进行额外的工作以确保参数可用。