§撰寫 Play 文件的指南

Play 文件採用 Markdown 格式撰寫，程式碼範例則從編譯、執行和測試過的原始碼檔案中擷取。

撰寫 Play 文件時，必須遵守一些準則。

§性別中立語言和名稱

Play 社群尊重性別多元性。在文件範例中撰寫時，請盡量使用性別中立語言和無性別名稱。如果您不確定正確的用詞，請尋求審閱者的協助。

§Markdown

所有 Markdown 檔案在整個文件中的名稱都必須是唯一的，無論它們位於哪個資料夾。Play 使用 wiki 風格的連結和呈現文件。

段落中間的新行字元被視為硬換行，類似於 GitHub 風格的 Markdown，並呈現為換行符號。因此，段落應包含在單一行中。

§連結

連結到文件中的其他頁面應使用 wiki 標記語法建立，例如

[[Optional description|ScalaRouting]]

圖片也應使用上述語法。

注意：外部連結不應使用上述語法，而應使用標準 Markdown 連結語法。

§程式碼範例

所有支援的程式碼範例都應從外部編譯檔案匯入。這樣做的語法為

@[some-label](code/SomeFeature.scala)

然後，檔案應使用 #some-label 界定需要擷取的行，例如

object SomeFeatureSpec extends Specification {
  "some feature" should {
    "do something" in {
      //#some-label
      val msg = Seq("Hello", "world").mkString(" ")
      //#some-label
      msg must_== "Hello world"
    }
  }
}

在上述情況中，val msg = ... 行將被擷取並呈現為頁面中的程式碼。應檢查所有程式碼範例以確保它們編譯、執行，並且如果合理，請確保它們執行文件所述的功能。它不應嘗試測試功能本身。

所有 scala/java/routes/templates 程式碼範例都在同一個類別載入器上執行。因此，它們都必須在與其關聯的文件部分相應應的套件中命名良好。

在某些情況下，文件中的程式碼可能無法與根據上述準則編寫的程式碼完全匹配。特別是，某些程式碼範例需要使用 controllers 等套件名稱。如果沒有其他方法可以解決這個問題，最後的手段是可以在程式碼中放置一些指令，指示程式碼範例擷取器修改範例。這些指令為

###replace: foo — 用 foo 取代下一行。您可以選擇使用 ### 結束此指令
###insert: foo — 在下一行之前插入 foo。您可以選擇使用 ### 結束此指令
###skip — 略過當前行
###skip: n — 略過接下來的 n 行

例如

//#controller
// ###replace: package controllers
package foo.bar.controllers

import javax.inject.Inject
import play.api.mvc._

class HomeController @Inject()(cc:ControllerComponents)
 extends AbstractController(cc) {
  ...
}
//#controller

這些指令只能作為最後的手段，因為將程式碼範例拉到外部檔案的重點在於，文件中所包含的程式碼也會被編譯和測試。指令會破壞這一點。

了解程式碼範例的當前內容也很重要，以確保適當的匯入陳述文件化。但是，在每個程式碼範例中包含所有匯入陳述沒有意義，因此必須在此處表現出謹慎。

以下是特定類型程式碼範例的指南。

§Scala

所有 scala 程式碼範例都應該使用規格進行測試，並且如果可能，程式碼範例應該在規格內。在適當的地方鼓勵使用局部類別和方法定義。也鼓勵在區塊內設定匯入陳述的範圍。

§Java

所有 Java 程式碼範例都應該使用 JUnit 進行測試。簡單的程式碼範例通常很容易包含在 JUnit 測試中，但當程式碼範例是方法或類別時，就會變得更困難。應優先使用區域和內部類別，但這可能無法實現，例如，靜態方法只能出現在靜態內部類別中，但這表示要將靜態修改器新增到類別中，而如果它是外部類別，則不會出現。因此，在某些情況下，可能需要將 Java 程式碼範例拉出到自己的檔案中。

§Scala 範本

Scala 範本程式碼範例應該使用 Scala 中的 Specs 或 Java 中的 JUnit 進行測試。請注意，範本會根據它們存在於 Scala 文件或 Java 文件中而編譯不同的預設匯入。因此，在正確的環境中測試它們也很重要。

在可能的情況下，範本程式碼範例應整合在單一檔案中，但這並不總是可行，例如，如果程式碼範例包含參數宣告。

§路由檔案

路由檔案應該使用 Scala 中的 Specs 或 Java 中的 JUnit 進行測試。路由檔案應以完整套件名稱命名，例如，scalaguide.http.routing.routes，以確保它們與其他路由程式碼範例隔離。

文件使用的路由編譯器在特殊模式下執行，會在該檔案所宣告的命名空間內產生反向路由器。這表示，儘管路由程式碼範例看似使用類別的絕對參照，但實際上是相對於路由器的命名空間。因此，在上述路由檔案中，如果您有一個稱為 controllers.Application 的路由，實際上會參照一個稱為 scalaguide.http.routing.controllers.Application 的控制器。

§sbt 程式碼

sbt 程式碼範例應萃取到 *.sbt 檔案。這些檔案會由 evaluateSbtFiles 任務個別進行測試，該任務會編譯並執行這些檔案 — 透過載入，表示它會執行設定定義（即建立 Seq[Setting[_]]，但不會實際執行宣告的任務或設定。用於執行這些檔案的類別載入器與 sbt 類別載入器相同，因此程式碼片段所需的任何外掛都必須是 sbt 專案的外掛。

§其他程式碼

其他程式碼可能可測試，也可能不可測試。使用 HTMLUnit 執行整合測試，測試 Javascript 程式碼可能是合理的。載入設定進行測試可能是合理的。在此應使用常識。

§測試文件

若要建立文件，您首先需要在本地建立並發佈 Play。您可以從 playframework 儲存庫的根目錄執行 sbt publishLocal 來執行此操作。

若要確保文件正確呈現，請從 documentation 目錄執行 sbt run。這將啟動一個小型 Play 伺服器，只負責提供文件。

若要確保程式碼範例編譯、執行和測試通過，請執行 sbt test。

若要驗證文件在結構上是否健全，請執行 sbt validateDocs。這會檢查是否有中斷的 wiki 連結、程式碼參考或資源連結，確保所有文件標記檔檔名都是唯一的，並確保沒有孤立的頁面。

下一步：翻譯文件

在此文件中發現錯誤？此頁面的原始程式碼可以在這裡找到。在閱讀文件指南後，請隨時貢獻一個 pull request。有問題或建議要分享？請前往我們的社群論壇與社群展開對話。