译者：小铁匠Linus；校对：Channe；定稿：numbbbbb
在Xcode7的所有功能中，有一个很特别：它给编写代码文档提供了一个更好的方法。随着Xcode7的更新，开发者可以使用Markdown语法书写富文本格式的代码文档，而且可以结合特定的关键词来指明特殊部分（如参数，函数返回结果等）。作为新支持的Markdown文档样式，它具有以下几点优势：文本样式的自定义程度更高，更加灵活，当然也更有趣。然而，如果你仍然对原来的文本样式感兴趣的话，也可以看以前那篇教程。
对每个开发者来说，代码文档是开发中非常重要的一件事。即使它看上去会拖慢开发进度，但实际上它是开发中不可或缺的一部分。我不反对给每个属性、函数、类、结构体等书写正确且全面的文档，但这并不是一件容易的事。不过，你可以通过以下几点来编写适当的文档：
描述各个属性、函数和类的真正用途。此外，最好能在需要注意的地方高亮函数的具体使用情况、用例或需求。
高亮函数的输入和输出（参数和返回值）。
为了几个月后再打开项目还能清晰地记得每个函数做了什么，每个属性是为了什么。
当你把代码共享或做成lib时，一定要让其他开发者能轻松地理解怎么使用你的代码。
使用工具制作具有专业外观的使用手册（比如：使用Jazzy）。
你在Xcode里写的代码文档能被预览，也可以用以下的三种方法访问：
按住Option/Alt键点击属性名、方法名或类名等，会弹出快速预览（QuickLookpreview）。
光标移动到属性名、方法名或类名上，打开快速帮助（QuickHelpInspector）进行查看。
使用第三方工具可以产生使用手册。比如，Jazzy就是这样一款工具，我们稍后会讲到。通过使用它，可以在你工程的文件夹里生成一个集成了所有你写的代码文档的网页。
代码文档不是很死板的东西；它可以根据各自实体（属性、方法、类、结构、枚举）的修改而改变。如果你没有在实现一个新的实体时添加文档的话，那么几乎可以肯定，你永远不会去添加文档了。因此，试着养成一个这样的习惯：在合适的时间点去书写代码文档，并在新的实体实现后能花时间去更新文档。
Markdown基础语法为了能更好地使用新的文档样式，对Markdown语法有一个基本的认识是很重要的。如果已经对这部分有充分的了解的话，可以跳过这一章，直接看下一章。你可以在网络上找到关于Markdown的很多信息，比如这里还有这里都能找到。
尽管你能找到关于Markdown语法的其他资源，但是我觉得至少要讲一下基础语法。我的目的当然不是要提供一整个Markdown使用指南，只是为了呈现特定语法的常见用法。
因此，你大概知道（可能现在才知道）Markdown语法是由特殊字符来格式化文本、添加资源（链接和图片）以及添加文本块（有序或无序列表，代码块等）。虽然这些字符很容易记住，但是还是需要经常上网查查或看看下面列出来的。有必要在这里说一下，如果你习惯了Markdown语法（其实很容易就做到了），然后通过使用合适的编辑器就可以生成不同格式的文档了，例如：HTML页面、PDF文档等等。说到HTML页面，Markdown支持内联HTML，也就是说，你可以直接把HTML标签写到文本里，这些标签都会被渲染。然而，使用HTML并不是Markdown的本质，因此我们还是回到Markdown自己的语法吧。
以下列出了最常用的Markdown语法：
#text#：文本标题，相当于HTML中的\
标签。两个#则对应\标签，以此类推，直到\标签。末尾的#可以省略。**text**：使文本具有加粗的效果。
*text*：使文本具有斜体的效果。
*text：使文本成为一个无序列表的元素，值得注意的是，有个*后面需要有一个空格。同样，可以使用+或-实现这个的功能。
text：使文本成为一个有序列表的元素。
[linkedtext](