此文件頁面專屬於 Scala 3，可能涵蓋 Scala 2 中沒有的新概念。除非另有說明，此頁面中的所有程式碼範例都假設您使用的是 Scala 3。
本章節說明如何正確撰寫文件字串，以及如何使用 scaladoc 的所有可用功能。由於許多內容與舊的 scaladoc 相同，因此某些部分重新使用自此 文章
Scaladoc 使用額外的功能擴充 Markdown，例如連結到 API 定義。這可以用於靜態文件和部落格文章中，以提供混合內容。
文件字串放置位置
Scaladoc 註解出現在它們在特殊註解區塊中所屬的項目之前，該區塊以 /** 開頭並以 */ 結尾，如下所示
/** 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.
*
* Close the comment with *\/
*
* If you use Scaladoc tags (@param, @group, etc.),
* remember to put them at separate lines with nothing preceding.
*
* For example:
*
* 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
在上面的範例中，此 Scaladoc 註解與方法 square 關聯，因為它在原始碼中就在其前面。
Scaladoc 註解可置於欄位、方法、類別、特質、物件之前。目前，scaladoc 不支援文件套件的直接解決方案。有一個專用的 github 問題，您可以在其中查看問題的目前狀態。
對於在 Scala 中與類別本身定義一致的類別主要建構函式，@constructor 標籤用於將註解設定為主要建構函式文件，而不是類別概觀。
標籤
Scaladoc 使用 @<tagname> 標籤在註解中提供特定詳細欄位。這些包括
類別特定標籤
- 置於類別註解中的
@constructor會描述主要建構函式。
方法特定標籤
@return詳細說明方法的回傳值（每個方法一個）。
方法、建構函式和/或類別標籤
@throws方法或建構函式可能會引發哪些例外（如果有）。@param詳細說明方法或建構函式的值參數，為方法/建構函式的每個參數提供一個。@tparam詳細說明方法、建構函式或類別的類型參數。每個類型參數提供一個。
用法標籤
@see參照其他資訊來源，例如外部文件連結或文件中的相關實體。@note新增預設或後設條件的備註，或任何其他值得注意的限制或預期。@example用於提供範例程式碼或相關範例文件。
成員群組標籤
這些標籤非常適合具有許多成員的較大型類型或套件。它們允許您將 Scaladoc 頁面組織成不同的區段，每個區段都單獨顯示，按照您選擇的順序顯示。
這些標籤預設未啟用！您必須將 -groups 標誌傳遞給 Scaladoc 才能啟用它們。通常，sbt 的做法會類似於
Compile / doc / scalacOptions ++= Seq(
"-groups"
)
每個區段應有一個單字識別碼，用於所有這些標籤中，如下所示 group。預設情況下，該識別碼會顯示為該文件區段的標題，但你可以使用 @groupname 提供較長的標題。
通常，你應該在 Scaladoc 中的套件/特質/類別/物件本身中放置 @groupprio（以及選擇性的 @groupname 和 @groupdesc），說明所有群組及其順序。然後在每個成員的 Scaladoc 中放置 @group，說明它屬於哪個群組。
沒有 @group 標籤的成員將在產生的文件中列為「未分組」。
@group <group>- 將實體標記為<group>群組的成員。@groupname <group> <name>- 為群組提供選擇性名稱。<name>會在群組說明之前顯示為群組標頭。@groupdesc <group> <description>- 新增選擇性說明文字，顯示在群組名稱下方。支援多行格式化文字。@groupprio <group> <priority>- 控制群組在頁面上的順序。預設為 0。未分組元素的隱含優先順序為 1000。使用 0 到 999 之間的值設定與其他群組的相對位置。較低的值會出現在較高的值之前。
其他標籤
@author提供下列實體的作者資訊@version此實體所屬系統或 API 的版本。@since類似@version，但定義此實體首次定義的系統或 API。@deprecated將實體標記為已棄用，提供應使用的替換實作，以及此實體已棄用的版本/日期。@syntax <name>讓你變更文件字串的剖析器。預設語法為 markdown，不過你可以使用此指令變更。目前可用的語法為markdown或wiki，例如@syntax wiki
巨集
@define <name> <definition>允許在同一個原始檔中的其他 Scaladoc 註解中使用 $name，它會擴充為<definition>的內容。
如果在目前的繼承層級中沒有提供實體的註解，但卻在繼承層級中較高層級的覆寫實體中提供了，則會使用父類別的註解。
同樣地，如果省略了 @param、@tparam、@return 和其他實體標籤，但卻可以在父類別中取得，則會使用那些註解。
明確
對於明確的註解繼承，請使用 @inheritdoc 標籤。
標記
Scaladoc 提供了兩個語法剖析器：markdown（預設）或 wikidoc。仍然可以在 Scaladoc 中嵌入 HTML 標籤（就像在 Javadoc 中一樣），但大多數時候並不需要，因為可以使用標記來代替。
Markdown
Markdown 使用 commonmark 風格，並有兩個自訂擴充功能
wikidoc連結，方便參照wikidoc程式碼區塊，使用大括弧語法
Wikidoc
Wikidoc 是用於 scala2 scaladoc 的語法。由於許多現有的原始碼，因此支援此語法，但不建議在新的專案中使用它。可以使用旗標 -comment-syntax wiki 全域啟用 wiki 語法，或是在文件字串中使用 @syntax wiki 指令。
一些可用的標準標記
`monospace`
''italic text''
'''bold text'''
__underline__
^superscript^
,,subscript,,
[[entity link]], e.g. [[scala.collection.Seq]]
[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]]
有關 wiki 連結的更多資訊，請參閱此 章節
其他格式化注意事項
- 段落以一個（或多個）空白行開始。註解中邊緣的
*是有效的（且應該包含），但其他部分的行應該空白。 - 標題定義時使用周圍的
=字元，更多的=表示子標題。例如=Heading=、==Sub-Heading==等。 - 清單區塊是一系列具有相同樣式和層級的清單項目，沒有其他區塊樣式的中斷。未排序的清單可以使用
-加上項目符號，編號清單可以使用1.、i.、I.或a.表示各種編號樣式。在這兩種情況下，前面都必須有額外的空白，更多的空白會形成子層級。
清單區塊的標記如下所示
/** Here is an unordered list:
*
* - First item
* - Second item
* - Sub-item to the second
* - Another sub-item
* - Third item
*
* Here is an ordered list:
*
* 1. First numbered item
* 1. Second numbered item
* i. Sub-item to the second
* i. Another sub-item
* 1. Third item
*/
撰寫 Scaladoc 註解的注意事項
簡潔明瞭！快速切入重點，人們花在文件上的時間有限，請明智地利用。省略不必要的字詞。優先選擇傳回 X，而不是此方法傳回 X，並執行 X、Y 和 Z，而不是此方法執行 X、Y 和 Z。DRY - 不要重複。避免在 @return 標籤和其他重複註解中複製方法說明。
更多關於撰寫 Scaladoc 的詳細資訊
有關格式化和樣式建議的更多資訊，請參閱 Scala-lang scaladoc 樣式指南。
連結到 API
Scaladoc 允許透過 Wiki 風格連結連結到 API 文件。連結到 scala.collection.immutable.List 就像 [[scala.collection.immutable.List]] 一樣簡單。有關確切語法的更多資訊，請參閱 文件註解文件。