為 Swift 代碼編寫含有 Mardown 語法的文檔

原文：Documenting Your Swift Code in Xcode Using Markdown
作者：GABRIEL THEODOROPOULOS
译者：kmyhy

在 Xcode 7 的所有新功能中，有一個最引人注目的新功能，能够讓你以更好的方式来书写代码文檔。從 Xcode 7 開始，開發者終於可以在他們的文檔中使用强大 Markdown 語法來進行富文本编辑了，Markdown 語法用一些特殊的關鍵字來描述文檔中的不同部分，比如參數、函數返回值等，從而使這些結構顯示出不同的樣式。新的 Markdown 文檔風格，最大的優點之一，是它允許對文本樣式進行更加靈活、徹底和豐富的定制。當然，如果你仍然想使用舊式的文檔風格，請參考先前的這篇教程。

對於每一個開發者而言，對代碼進行文檔化是一種極好的習慣。雖然它表面上看起來會對開發進度有一定的影響，但这本身亦应当属于開發过程的一部分。這並不意味著我們要對項目中存在的屬性、函数、類、結構或其它每一樣東西事無巨細地编到文档中去，這根本是不可能的事情。而是應該“合理”文檔化，也就是：

• 描述類、方法和屬性的用途，粗略程度要適當。而且最好對調用方法時應當注意的前提條件、事項或限制做重點說明。
• 高亮標出方法的輸入/輸出（參數及返回值）。
• 當你事隔幾個月再次閱讀項目代碼時，代碼中每一個方法的用途和每一個屬性的意義你都能輕鬆憶起。
• 當你分享代碼或庫時，別的開發者能夠很容易就明白這些代碼要如何使用。
• 通過某些工具（例如 Jazzy），我們就能生成專業的幫助文檔。

在 Xcode 中編寫的代碼文檔可以通過三種方法進行預覽：

• 在屬性名、方法名或類名上點擊 Option/Alt＋鼠標左鍵。你就可以在這些名字的右側或者下方看到屬性、方法或類的快速概覽(Quick Look Preview)。
• 把鼠標放到屬性名、方法名或類名上，則會打開快速幫助檢視器（Quick Help Inspector）。
• 有一些第三方工具能夠將代碼中的文檔製作成標準幫助文檔，例如 Jazzy，我們稍後會介紹它。通過 Jazzy，你的文檔將會以網頁的形式編譯，同時所有的網頁會生成到項目文件夾下的一個子文件中，這些網頁構成了一個可獨立咝械

  （编辑：李大同）

  【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!