documenting-rust-code

此技能為 HASH 儲存庫中的 Rust 程式碼編寫提供了一套全面的文件規範。它通過建立關於文件註解、函式說明、型別規格和模組級文件的清晰標準，確保遵循 rustdoc 的規範。此技能旨在為從事 HASH 程式庫開發的工程師提供指導，確保所有公開 API 都能正確標註，並透過內部文件連結 (intra-doc links) 保持易維護性與可發現性，效仿 serde、time 和 jiff 等高效能 crate 的社群標準。

• 標準化文件註解的結構，要求以簡潔的單行摘要作為開頭，隨後進行詳細說明。

• 強制要求所有型別參考使用內部文件連結，以提升 IDE 導航與文件網站的使用性。

• 定義錯誤文件的強制格式，要求所有可能失敗的函式必須包含顯式的 # Errors 章節。

• 鼓勵為公開 API 加入實用的範例，並確保這些範例有效且可透過 cargo doc 驗證。

• 不建議對 Debug、Display 或 From 等標準 trait 實作撰寫冗餘說明，並禁止使用獨立的 # Returns 章節，改採行內描述方式。

• 當您在 HASH 專案中為新的 Rust 模組、函式、結構或 trait 撰寫文件時，請使用此技能。

• 針對 0-2 個參數的簡單函式與需要 # Arguments 章節的複雜函式，請遵循指定的編寫模式。

• 請務必連結如 Vec 或 HashMap 等標準函式庫型別，以確保清晰度並符合標準規範的交叉引用。

• 在提交變更之前，請透過執行 cargo doc --no-deps --all-features 在本地驗證文件的準確性與格式。

• 請將文件註解與程式碼行分開，以確保閱讀性並遵守標準 Rust 風格指南。