轻松记录您
灵感和创意

在 Xcode 中使用 Markdown 生成 Swift 代码文档

在 Xcode 7 的所有功能中,有一个很特别:它给编写代码文档提供了一个更好的方法。随着 Xcode 7 的更新,开发者可以使用 Markdown 语法书写富文本格式的代码文档,而且可以结合特定的关键词来指明特殊部分(如参数,函数返回结果等)。作为新支持的 Markdown 文档样式,它具有以下几点优势:文本样式的自定义程度更高,更加灵活,当然也更有趣。然而,如果你仍然对原来的文本样式感兴趣的话,也可以看以前那篇教程。

对每个开发者来说,代码文档是开发中非常重要的一件事。即使它看上去会拖慢开发进度,但实际上它是开发中不可或缺的一部分。我不反对给每个属性、函数、类、结构体等书写正确且全面的文档,但这并不是一件容易的事。不过,你可以通过以下几点来编写适当的文档:

描述各个属性、函数和类的真正用途。此外,最好能在需要注意的地方高亮函数的具体使用情况、用例或需求。

高亮函数的输入和输出(参数和返回值)。

为了几个月后再打开项目还能清晰地记得每个函数做了什么,每个属性是为了什么。

当你把代码共享或做成 lib 时,一定要让其他开发者能轻松地理解怎么使用你的代码。

使用工具制作具有专业外观的使用手册(比如:使用 Jazzy)。

你在 Xcode 里写的代码文档能被预览,也可以用以下的三种方法访问:

按住  Option/Alt 键点击属性名、方法名或类名等,会弹出快速预览(Quick Look preview)。

光标移动到属性名、方法名或类名上,打开快速帮助(Quick Help Inspector)进行查看。

使用第三方工具可以产生使用手册。比如,Jazzy 就是这样一款工具,我们稍后会讲到。通过使用它,可以在你工程的文件夹里生成一个集成了所有你写的代码文档的网页。

代码文档不是很死板的东西;它可以根据各自实体(属性、方法、类、结构、枚举)的修改而改变。如果你没有在实现一个新的实体时添加文档的话,那么几乎可以肯定,你永远不会去添加文档了。因此,试着养成一个这样的习惯:在合适的时间点去书写代码文档,并在新的实体实现后能花时间去更新文档。

Markdown 基础语法

为了能更好地使用新的文档样式,对 Markdown 语法有一个基本的认识是很重要的。如果已经对这部分有充分的了解的话,可以跳过这一章,直接看下一章。你可以在网络上找到关于 Markdown 的很多信息,比如这里还有这里都能找到。

尽管你能找到关于 Markdown 语法的其他资源,但是我觉得至少要讲一下基础语法。我的目的当然不是要提供一整个 Markdown 使用指南,只是为了呈现特定语法的常见用法。

因此,你大概知道(可能现在才知道)Markdown 语法是由特殊字符来格式化文本、添加资源(链接和图片)以及添加文本块(有序或无序列表,代码块等)。虽然这些字符很容易记住,但是还是需要经常上网查查或看看下面列出来的。有必要在这里说一下,如果你习惯了 Markdown 语法(其实很容易就做到了),然后通过使用合适的编辑器就可以生成不同格式的文档了,例如:HTML 页面、PDF 文档等等。说到 HTML 页面,Markdown 支持内联 HTML,也就是说,你可以直接把 HTML 标签写到文本里,这些标签都会被渲染。然而,使用 HTML 并不是 Markdown 的本质,因此我们还是回到 Markdown 自己的语法吧。

以下列出了最常用的 Markdown 语法:

#text#:文本标题,相当于 HTML 中的 \

标签。两个 # 则对应 \标签,以此类推,直到 \标签。末尾的 # 可以省略。

**text**:使文本具有加粗的效果。

*text*:使文本具有斜体的效果。

* text:使文本成为一个无序列表的元素,值得注意的是,有个 * 后面需要有一个空格。同样,可以使用 + 或 – 实现这个的功能。

text:使文本成为一个有序列表的元素。

[linked text](http://some-url.com):使文本成为可以点击的超链接。

text:创建一个块引用。

使用 4 个空格或 1 个 tab 来缩进所写的代码块,等价于 HTML 中的 \

\

标签。可以继续使用 4 个空格或 1 个 tab 来添加另一个缩进。

如果不想使用空格或 tab 的话,可以使用 。比如, myProperty 会显示成 var myProperty。 另一种创建代码块的方法是添加 4 个 ,并从下一行开始写具体的代码,最后添加 4 个 ` 表示结束。

反斜杠修饰 Markdown 的特殊字符就可以避免 Markdown 语法的解析了。比如, \**this\** 就不会产生加粗的效果。

以上这些是 Markdown 语法中比较重要的部分。虽然,Markdown 语法中还有很多额外的细节可以深究。但是,以上提供的这些已经足够你开始使用 Markdown 了。

如果你发现 Markdown 还蛮有意思的话,你可以下载一个编辑器具体尝试一下。使用编辑器,你可以实时地看到你所写的文本在转化成 HTML 后的效果。

关于编辑器:你可以尝试以下这些 Markdown 编辑器:StackEdit,Typora,Macdown,Focused 和 Ulysses。

未经允许不得转载:坚果云Markdown » 在 Xcode 中使用 Markdown 生成 Swift 代码文档
分享到: 更多 (0)

坚果云Markdown轻松记录您 灵感和创意

坚果云Markdown下载坚果云Markdown介绍