Swift有文档注释或工具吗？

文档注释在Xcode中原生支持，在快速帮助中生成智能呈现文档(在咔嗒按钮符号和快速帮助检查器??2中的弹出框中)。

符号文档注释现在基于同样的Markdown syntax使用丰富的操场注释，所以很多你可以在操场中做的现在可以直接在源代码文档中使用。

有关语法的完整详细信息，请参阅Markup Formatting Reference.请注意，在丰富的playground注释和语法的语法之间存在一些差异。符号文档;这些都在文档中指出(例如块引号只能在游乐场中使用)。

下面是一个示例，以及当前用于符号文档注释的语法元素列表。

更新

Xcode 7 beta 4?添加了“ – Throws：…”作为顶级列表项，它显示在快速帮助中的参数和返回说明旁边。

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:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - 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)

注释样式

支持生成文档注释的///(inline)和/ ** * /(block)样式注释。虽然我个人喜欢/ ** * /评论的视觉风格，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

你也可以使用or *作为无序列表，它只是必须是一致的。

有序(编号)列表：

/// 1. Item 1
/// 2. Item 2
/// 3. Item 3

代码块：

///    for item in array {
///        print(item)
///    }

需要至少四个空格的缩进。

内联元素

强调(斜体)：

/// 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)

图片：

/// ![Alt Text](http://www.example.com/alt-image.jpg)

URL可以是网址(使用“http：//”)或绝对文件路径URL(我似乎无法获得相对文件路径工作)。

链接和图片的网址也可以与内联元素分隔开，以便将所有网址保留在一个易于管理的位置：

/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg

关键词

除了Markdown格式之外，Xcode还可以识别其他标记关键字，以便在快速帮助中显示。这些标记关键字通常采用格式 – < keyword&gt ;:(异常是参数，其还包括冒号之前的参数名称)，其中关键字本身可以用大写/小写字符的任何组合来写。 符号节关键字 以下关键字在帮助查看器中的“说明”部分下方和“已声明的部分”上方显示为突出部分。如果包含，它们的顺序是固定的，如下所示，即使您可以按您喜欢的任何顺序包括在您的评论。 请参阅完全记录的部分关键字列表及其在Symbol Section Commands section of the Markup Formatting Reference中的预期用途。

/// - parameters:
///   - <#parameter name#>:
///   - <#parameter name#>:
/// - throws:
/// - returns:

或者，您可以这样写每个参数：

/// - parameter <#parameter name#>:

符号说明字段关键字

以下关键字列表在帮助查看器的“说明”部分的正文中显示为粗体标题。它们将以您写入它们的任何顺序出现，与“说明”部分的其余部分一样。

完整列表从this excellent blog article由Erica Sadun释义。另请参阅完整记录的关键字列表及其在Symbol Description Field Commands section of the Markup Formatting Reference中的预期用途。

归属：

/// - author:
/// - authors:
/// - copyright:
/// - date:

可用性：

/// - since:
/// - version:

警告：

/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:

开发状态：

/// - bug:
/// - todo:
/// - experiment:

实施质量：

/// - complexity:

函数语义：

/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:

交叉参考：

/// - seealso:

导出文档

HTML文档(旨在模仿苹果自己的文档)可以使用Jazzy(一个开源命令行实用程序)从内联文档生成。

$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ?? to your fresh new docs in `docs`

控制台示例取自this NSHipster article