Swift是否有文档注释或工具？
许多语言支持文档注释以允许生成器（如javadoc或doxygen ），通过parsing相同的代码来生成代码文档。
Swift是否有任何types的文档注释或文档生成工具？
文档注释在Xcode中本地支持，在快速帮助中生成巧妙呈现的文档（在pop单击符号的popup窗口以及Quick Help Inspector⌥⌘2中）。
符号文档注释现在基于丰富的操场注释所使用的相同Markdown语法 ，因此现在可以在源代码文档中直接使用许多在操场上可以做的事情。
有关语法的完整详细信息，请参阅标记格式参考 。 请注意，丰富的游乐场评论和符号文件的语法有一些差异; 这些都在文件中指出（例如块引用只能在游乐场中使用）。
以下是符号文档注释当前工作的语法元素的示例和列表。
更新
Xcode 7 beta 4〜增加了“ - Throws: ... ”作为顶级列表项目，它与Quick Help中的参数和返回描述一起出现。
Xcode 7 beta 1〜Swift 2语法上的一些重大变化 – 现在基于Markdown的文档注释（与游乐场相同）。
Xcode 6.3（6D570）〜缩进文本现在被格式化为代码块，随后的缩进被嵌套。 在这样的代码块中，看起来不可能留下空白的行 – 试图这样做的结果是文本被加到最后一行的末尾，其中包含任何字符。
Xcode 6.3 beta〜内联代码现在可以使用反引号添加到文档注释中。
Swift 2的示例
/// Text like this appears in "Description". /// /// Leave a blank line to separate further text into paragraphs. /// /// You can use bulleted lists (use `-`, `+` or `*`): /// /// - Text can be _emphasised_ /// - Or **strong** /// /// Or numbered lists: /// /// 7. The numbers you use make no difference /// 0. The list will still be ordered, starting from 1 /// 5. But be sensible and just use 1, 2, 3 etc… /// /// --- /// /// More Stuff /// ========== /// /// Code /// ---- /// /// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage: /// /// // Create an integer, and do nothing with it /// let myInt = 42 /// doNothing(myInt) /// /// // Also notice that code blocks scroll horizontally instead of wrapping. /// /// Links & Images /// -------------- /// /// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images: /// ///  /// /// - note: That "Note:" is written in bold. /// - requires: A basic understanding of Markdown. /// - seealso: `Error`, for a description of the errors that can be thrown. /// /// - parameters: /// - int: A pointless `Int` parameter. /// - bool: This `Bool` isn't used, but its default value is `false` anyway… /// - throws: A `BadLuck` error, if you're unlucky. /// - returns: Nothing useful. func doNothing(int: Int, bool: Bool = false) throws -> String { if unlucky { throw Error.BadLuck } return "Totally contrived." }
Swift 2的语法（基于Markdown ）
评论风格
生成文档注释时都支持/// （内联）和/** */ （块）样式注释。 虽然我个人比较喜欢/** */ comments的视觉风格，但是在复制/粘贴时，Xcode的自动缩进可能会破坏此评论样式的格式，因为它会删除前导空白。 例如：
/** See sample usage: let x = method(blah) */
粘贴时，代码块缩进将被删除，不再呈现为代码：
/** See sample usage: let x = method(blah) */
出于这个原因，我通常使用/// ，并将其用于此答案中的其余示例。
块元素
标题：
/// # My Heading
要么
/// My Heading /// ==========
副标题：
/// ## My Subheading
要么
/// My Subheading /// -------------
横向规则：
/// ---
无序（项目符号）列表：
/// - An item /// - Another item
您也可以使用+或*作为无序列表，它只需要一致。
有序（编号）列表：
/// 1. Item 1 /// 2. Item 2 /// 3. Item 3
代码块：
/// for item in array { /// print(item) /// }
至less需要四个空格的缩进。
内联元素
重点（斜体）：
/// Add like *this*, or like _this_.
强（粗体）：
/// You can **really** make text __strong__.
请注意，不能在同一元素上混合使用星号（ * ）和下划线（ _ ）。
内联代码：
/// Call `exampleMethod(_:)` to demonstrate inline code.
链接：
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
图片：
/// 
该URL可以是url（使用“http：//”）或绝对文件pathURL（我似乎无法获取相关文件path）。
链接和图像的URL也可以与内联元素分开，以便将所有URL保存在一个可pipe理的位置：
/// A [link][1] an an ![image][2] /// /// ... /// /// [1]: http://www.example.com /// [2]: http://www.example.com/image.jpg
关键词
除了Markdown格式之外，Xcode还可以识别其他标记关键字，以便在“快速帮助”中显示。 这些标记关键字大多采取格式- <keyword>:例外是parameter ，其中还包括冒号前的参数名称），其中关键字本身可以用大写/小写字符的任意组合来书写。
符号部分关键字
以下关键字在帮助查看器中显示为突出部分，位于“说明”部分下方，以及“声明为”部分上方。 如果包含，即使您可以按照您的意见中的任何顺序包含它们，但其顺序如下所示。
请参阅“ 标记格式参考”的“ 符号部分命令”部分中完整logging的部分关键字列表及其预期用途。
/// - parameters: /// - <#parameter name#>: /// - <#parameter name#>: /// - throws: /// - returns:
或者，你可以这样写每个参数：
/// - parameter <#parameter name#>:
符号说明字段关键字
以下关键字列表在帮助查看器的“说明”部分的主体中显示为粗体标题 。 它们将按照您所写入的顺序显示，与“说明”部分的其余部分一样。
从Erica Sadun的这篇优秀的博客文章转述完整列表。 另请参阅“ 标记格式参考”的“ 符号说明字段命令”部分中完整logging的关键字列表及其预期用途。
归因：
/// - author: /// - authors: /// - copyright: /// - date:
可用性：
/// - since: /// - version:
告诫：
/// - attention: /// - important: /// - note: /// - remark: /// - warning:
发展状态：
/// - bug: /// - todo: /// - experiment:
实施质量：
/// - complexity:
function语义：
/// - precondition: /// - postcondition: /// - requires: /// - invariant:
相互参照：
/// - seealso:
导出文档
HTML文档（旨在模仿Apple自己的文档）可以使用开源的命令行实用程序Jazzy通过内联文档生成。
$ [sudo] gem install jazzy $ jazzy Running xcodebuild Parsing ... building site jam out ♪♫ to your fresh new docs in `docs`
从这个NSHipster文章取得控制台的例子
下面是在Xcode 6中loggingswift代码的一些工作。它对冒号很敏感，但是比没有好。
class Foo { /// This method does things. /// Here are the steps you should follow to use this method /// /// 1. Prepare your thing /// 2. Tell all your friends about the thing. /// 3. Call this method to do the thing. /// /// Here are some bullet points to remember /// /// * Do it right /// * Do it now /// * Don't run with scissors (unless it's tuesday) /// /// :param: name The name of the thing you want to do /// :returns: a message telling you we did the thing func doThing(name : String) -> String { return "Did the \(name) thing"; } }
上面的内容在快速帮助中呈现，就像您期望的格式化数字列表，项目符号点，参数和返回值文档一样。
这些都没有logging – 提交雷达帮助他们。
Swift包含“///”注释处理（尽pipe可能不是所有的东西）。
写下类似于：
/// Hey! func bof(a: Int) { }
然后点击function名称和voilà:)
Xcode 8中的新function ，你可以select一个像这样的方法
func foo(bar: Int) -> String { ... }
然后按下command + option + /或从Xcode的“编辑器”菜单中select“结构” – “添加文档” ，它将为您生成以下评论模板：
/// <#Description#> /// /// - parameter bar: <#bar description#> /// /// - returns: <#return value description#>
我可以证实ShakenManChild提供了peopr解决scheme
只要确定，你的描述下方有一个空行。
如果你只使用Swift，那么Jazzy值得一看。
是。 基地常见（我做了与Obj-C等效的片段）
Objective-C的：
/** @brief <#Short description - what it is doing#> @discussion <#Description#> @param <#paramName#> <#Description#>. @return <#dataType#> <#Description#>. */
迅速
/** <#Short inline description - what it is doing#> <#Description#> :param: <#paramName#> <#Description#>. :returns: <#dataType#> <#Description#>. */
我发现了一些有趣的东西，在Xcode二进制文件中挖掘。 以.swiftdoc结尾的.swiftdoc 。 它肯定有文档，因为这些文件包含了Swift UIKit / Foundation API的文档，不幸的是它似乎是专有的文件格式，可以在Xcode的文档查看器中使用。
您可以使用Docco在Swift中进行文字 编程 。
在Xcode编辑器 – >结构 – >添加文档。
也许最好先关注一下AppleDoc或者Apple自己的HeaderDoc ，这个东西很难被认识到。 我仍然可以在10.9 Mavericksterminal（headerdoc2html）中find一些HeaderDoc提示，
我推荐阅读最新的“ Xcode中的新function ”*（不知道它是否仍然在NDA之下）*链接指向Xcode 5.1版本也包含关于HeaderDoc的信息。
从Xcode 5.0起，支持Doxygen和HeaderDoc结构注释。
资源
