在 Xcode 中,良好的文檔注釋能讓開發者透過 Option 點擊快速理解方法用途。本文整理常見寫法,包含多行注釋、單行注釋、Markdown 語法與常用關鍵字。

最常見的是在方法上方使用 /** 包圍的多行注釋,也可以使用 /// 撰寫單行注釋。若需要多段說明,單行寫法每一行都要加上 ///,並以空行分隔段落。



文檔注釋可使用 Markdown。段落之間以空行分隔;無序清單可用 -、+ 或 *;有序清單可用數字加句點。若要插入程式碼,可使用三個反引號包圍。標題、粗體、連結與圖片也都能呈現。

參數說明可使用 parameter 或 parameters。若要說明回傳值,可使用 returns。若方法可能拋出錯誤,可使用 throws。其他常見標籤還包括 author、version、copyright、since、note、warning 與 complexity。



寫文件注釋時,建議先描述目的,再補充參數、回傳值與注意事項。保持格式一致,能讓團隊更容易閱讀與維護。