提供所有套件、類別、特質、方法和其他成員的文件非常重要。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 for Library Authors 以取得有關格式化 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）。對於 curried 函數，請考慮提供有關預期或慣用語法的更詳細範例。對於隱含參數，請特別注意說明這些參數的來源，以及使用者是否需要執行任何額外工作來確保參數可用。