內容

dart doc 指令會為 Dart 原始碼產生 HTML 參考文件。

撰寫文件

#

若要將參考文字和範例新增到產生的文件中,請使用 文件註解 搭配 Markdown 格式。有關撰寫文件註解的指南,請參閱 Effective Dart: 文件 指南。

產生 API 文件

#

若要產生套件的文件,請從套件的根目錄執行 dart doc .。例如,產生 my_package 套件的 API 文件可能類似於以下內容

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

預設情況下,dart doc 會將產生的文件和支援檔案放置在 doc/api 目錄中。若要變更輸出目錄,請使用 --output 旗標指定路徑

$ dart doc --output=api_docs .

如果您的套件設定或文件註解有任何問題,dart doc 會將它們輸出為錯誤或警告。如果您只想測試問題而不儲存產生的文件,請新增 --dry-run 旗標

$ dart doc --dry-run .

設定產生

#

若要設定 dart doc 產生文件的配置,請在套件的根目錄中建立一個名為 dartdoc_options.yaml 的檔案。

若要深入了解檔案格式和支援的設定選項,請參閱 dart.dev/go/dartdoc-options-file

檢視產生的文件

#

您可以透過各種方式檢視使用 dart doc 產生的文件。

檢視本機文件

#

若要檢視您使用 dart doc 產生或從線上下載的 API 文件,您必須使用 HTTP 伺服器載入它們。

要提供檔案,請使用任何 HTTP 伺服器。考慮使用 pub.dev 中的 package:dhttpd

要使用 package:dhttpd,請先在全球啟用它,然後執行它並指定您產生的文件路徑。以下指令會啟用套件,然後執行它來提供位於 doc/api 的 API 文件

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

然後在瀏覽器中閱讀產生的文件,請開啟 dhttpd 輸出的連結,通常是 http://localhost:8080

檢視已主機的文件

#

您也可以使用任何支援靜態網路內容的託管服務,在線上託管您產生的 API 文件。兩個常見的選項是 Firebase 託管GitHub 頁面

檢視套件文件

#

pub.dev 網站 會為上傳套件的公開函式庫產生並託管文件。

要檢視套件產生的文件,請瀏覽到其頁面,然後開啟頁面右側資訊方塊中的API 參考連結。例如,您可以在 pub.dev/documentation/http 找到 package:http 的 API 文件。

檢視核心函式庫文件

#

dart doc 也用於為 Dart 核心函式庫產生 API 參考文件。

要檢視 Dart SDK 參考文件,請拜訪與您開發時使用的 Dart 發行頻道對應的 api.dart.dev 連結

分支產生的文件
穩定版api.dart.dev/stable
測試版api.dart.dev/beta
開發版api.dart.dev/dev
主要版本api.dart.dev/main

疑難排解

#

要找出並解決使用 dart doc 產生的文件常見問題,請參閱以下參考部分。

#

如果產生的文件的搜尋列無法運作,或包含類似「無法初始化搜尋」的文字,則可能發生以下情況之一

  1. 您從自己的檔案系統存取文件,但它們並未提供服務,也未載入 HTTP 伺服器。要了解如何提供本機 API 文件,請查看 如何在地端檢視產生的文件
  2. dart doc 產生的 index.json 檔案遺失或無法從文件目錄或您的託管網路伺服器存取。請嘗試重新產生文件並驗證您的託管設定。

側邊欄載入失敗

#

如果產生的文件的側邊欄遺失或包含類似「無法載入側邊欄」的文字,則可能發生以下情況之一

  1. 您正在從自己的檔案系統存取文件,但文件並未透過 HTTP 伺服器提供服務並載入。如需了解如何提供本機 API 文件服務,請查看如何檢視本機文件
  2. 已設定產生文件的 base-href 行為。此組態選項已過時,不應再使用。請嘗試移除選項並使用 dart doc 的預設行為。如果預設行為中斷您產生文件中連結,請提交問題

缺少 API 文件

#

如果您找不到或無法存取預期有文件的 API 的產生文件,則可能是下列情況之一

  1. 套件未將您正在尋找的 API 公開為公開 API。dart doc 僅為公開函式庫和公開供其他套件匯入和使用的成員產生文件。如需深入了解如何設定套件的公開函式庫,請查看公開函式庫的套件配置指南。
  2. 您嘗試存取的網址大小寫不正確。預設情況下,dart doc 會產生大小寫敏感、與其對應來源宣告相符且附檔名為 .html 的檔名。請嘗試驗證網址是否符合這些預期。

應顯示圖示的文字

#

如果您看到文字而非圖示(例如功能表和佈景主題按鈕),則您的瀏覽器可能無法載入 Material Symbols 字型。解決此問題的一些選項包括

  1. 嘗試使用可存取 Google Fonts 伺服器的代理伺服器。
  2. 更新產生頁面以使用字型的本機版本。