函式庫作者建立資訊豐富文件的最佳實踐
您為函式庫提供的文件至關重要。它能決定使用者是否會研究您的函式庫、在專案中採用它，以及在遇到困難時是否會堅持下去。現今的開發人員在語言、函式庫、框架和平台之間擁有前所未有的選擇。因此，吸引並告知您的使用者至關重要；否則他們可能會尋求其他選項。
在您的函式庫最早版本中，來自使用者的回饋會很少。幸運的是，建立和完善文件可以作為一個回饋循環，大大提高您專案的品質。因此，建立文件絕不應被視為一種負擔，在建立函式庫時也不應被推到優先級列表的末尾。
有效的文件不僅能告知使用者，還能推動您函式庫的開發和完善。以下是文件如何引導您開發過程的幾個關鍵方式：
- 您應該能夠用幾段文字解釋您的函式庫做什麼、誰將受益於使用它，以及它相對於其他方法有何優勢。如果您無法做到這一點，請重新考慮您專案的範圍和目標。
- 您應該能夠建立一份「入門指南」，讓潛在使用者盡快上手並執行。盡快 的定義將取決於問題領域，但您可以與其他平台上類似的函式庫進行比較。該指南應將使用者引入一個回饋循環，使其越來越容易和快速，同時始終產生可靠的結果。建立此指南將幫助您識別可能阻礙使用者進度的複雜性突然增加（斷崖式難度）的情況。
- 記錄函數的行為會迫使您考慮所有邊緣情況，例如輸入的有效範圍、可能拋出的例外，以及隨著工作量增加效能如何下降。這通常會導致函數簽章和底層實作的改進。
- 如果初始化您的函式庫所需的程式碼總是比完成一項任務所需的程式碼多，請重新考慮您的設定選項。
- 如果您無法建立使用標準選項執行基本任務的清晰範例，請考慮為日常使用優化您的 API。
- 如果您無法展示如何在不使用真實資料來源和線上服務的情況下測試您的函式庫，請考慮為存取網路（以及通常意義上的外部世界）的元件提供測試替身 (test doubles)。
您越早為您的函式庫提供文件，它就能越早由實際使用者進行測試。這些測試的回饋隨後可用於改進設計。
提供全面文件
您的函式庫必須提供足夠的文件，讓使用者以最小的努力採用它。此文件應包含：
- 入門指南
- API 的深入描述
- 常用案例的更長範例（也稱為食譜 (recipes)）
- 連結至部落格、文章、網路研討會和會議演講等資源
入門指南應涵蓋您的函式庫如何與支援的建置系統整合。它應包含最常用實體的簡要描述，並附帶使用方式的小範例。在函式庫與外部世界互動的每個點，請指定設定環境的必要步驟，以及如何驗證這些步驟已成功完成。如果不需要任何步驟，請明確說明。
如果可能，請為您支援的每個函式庫版本提供單獨的文件版本。這可以防止使用者查閱過時或過於新穎的資訊。當這不可行時，請清楚標記文件中與已重新設計的 API 部分相關的區塊。
為您的使用者建立人物誌
在不清楚目標受眾的情況下建立和評估文件是具有挑戰性的。為將閱讀您文件的使用者類型定義多個人物誌會很有幫助。
考慮使用者的限制，例如他們需要操作的現有軟體堆疊。文件的審閱者可以採用這些人物誌，使他們的結論更有意義。
當您缺乏關於使用者的具體資訊時，最好保持悲觀。例如，不要假設使用者精通 Kotlin 的最新或最進階功能。盡可能保持您的程式碼範例簡單。
當因時間、預算限制或保密協議而無法諮詢實際使用者時，人物誌尤其有用。隨著時間的推移，當您對使用者有更好的理解時，請完善人物誌以更準確地符合他們的需求。
盡可能以範例進行文件撰寫
透過範例撰寫文件是向使用者解釋基本概念最具成本效益的方法之一。盡可能提供簡單明瞭的程式碼範例，以幫助解釋或示範當前討論的主題或概念。
KDoc 文件格式允許您在文件註解中使用 Markdown 內聯標記。在註解中使用內聯程式碼片段來展示 API 的用法。例如，請參閱 coroutines 函式庫中測試 Dispatcher 的 原始碼 和 渲染後的文件。
提供這樣的範例可以避免撰寫冗長的預期輸入、可能輸出和失敗模式的描述。然而，每個範例的上下文需要清晰，並且其相關情況也需要明確。簡單地提供一個沒有註解的範例程式資料夾不符合文件的要求。
徹底記錄您的 API
每個受支援的 API 進入點都應使用 KDoc 進行記錄。
Kotlin 的文件引擎 Dokka 預設只在其輸出中包含公開宣告。如 簡潔性 部分所討論，您應該最小化您的公開 API，並移除您不想讓使用者存取的公開進入點。如果有些 API 無法透過控制其可見性來向使用者隱藏，請使用 抑制指令 將其從文件中省略。
以清晰、高層次的描述函數功能的內容來開始進入點的描述。避免僅僅用自然語言重述簽章。
例如，不要說「接受一個 String 並回傳一個 Connection」，而是或許說「嘗試連線到由輸入字串指定的資料庫，如果成功則回傳一個 Connection，否則拋出 ConnectionTimeoutException」。
指定每個輸入的預期值以及不同輸入下的行為。解釋有效值的範圍以及提供無效值時會發生什麼。例如，如果一個字串輸入應該是 URL，請描述當字串為空、無效、使用不支援的協定，或指向不存在的位置時會發生什麼。
記錄 API 進入點可能拋出的每一個例外。在一般描述中討論失敗條件，並將例外區塊保留給詳細資訊。這能增強可讀性並幫助讀者集中注意力。相反地，將這些資訊有機地納入一般描述中。盡可能提供使用範例也有助於使用者理解如何正確使用 API。
記錄 Lambda 參數
當 API 進入點接受一個 lambda 時，使用者正在提供某些功能，您的函式庫將代表他們執行這些功能。這至少需要在兩個方面進行額外文件撰寫。
首先，記錄如果 lambda 拋出例外會發生什麼。考慮解決以下問題：
- 這會導致立即失敗嗎？lambda 會被重複呼叫嗎？還是有備用行為？
- 如果呼叫函數需要退出，它會重新拋出從 lambda 拋出的例外還是不同的例外？
- 如果例外不同，它會包含原始例外嗎？
此外，除非函數宣告為 inline，否則請記錄與並行相關的任何特殊行為。確保涵蓋以下內容：
- lambda 會在與呼叫者相同的執行緒中被呼叫嗎？
- 如果 lambda 不在與呼叫者相同的執行緒中被呼叫，它會在哪個執行緒（或執行緒池）中被呼叫？
- lambda 的多個副本可以並行執行嗎？
- 還有哪些其他工作可能正在使用該執行緒？
- 使用者可以指定函式庫要使用的執行緒嗎？
- 當多個 lambda 被呼叫時，關於排序有提供哪些保證？
在文件中使用明確連結
API 進入點完全獨立於函式庫中其他功能的情況非常罕見。通常，呼叫必須以特定順序進行，執行特定任務有多種選項，並且執行相關任務的進入點以相似方式使用。例如，像 format 和 parse 這樣的函數彼此對應。
使用 @see 標籤或 內部連結 在您的文件中明確這些關係。這有助於讀者將資訊 分塊 組合在一起，建立更好的整合式函式庫心智圖。
盡可能保持獨立
在描述什麼使輸入有效時，很容易只提及相關標準，例如由 W3C、IEEE 或 Unicode Consortium 產生的標準。雖然提供這些連結可能有所幫助，但讀者不應被迫參閱外部規範才能發現基本資訊，例如空白字元集。
盡可能地，文件應保持獨立。它應提供足夠的資訊，讓使用者理解每個 API 進入點的典型用法。您可以將使用者參照到外部文件，以瞭解在常見用法中不會發生的邊緣情況。
使用簡單英文
在撰寫文件時，使用簡單清晰的英文很重要。這確保您的內容可供全球受眾存取，包括那些母語不是英文的人。避免使用可能讓讀者感到困惑的複雜詞彙、行話、拉丁短語或慣用語。相反地，使用直接的語言和簡潔的句子。
簡單英文也使文件在需要時更容易翻譯。清晰、無歧義的文字可以降低誤解的風險，並提高整體可讀性。
下一步
如果您尚未閱讀，請考慮查閱這些頁面：