swift - Swift 有文档生成支持吗？

Question

多国语言支持文档注释 允许生成器(如 javadoc 或 doxygen )通过解析相同的代码来生成代码文档。

Swift 有这样的类型文档注释功能吗？

Answer 1

Xcode 本身支持文档注释，在快速帮助中生成智能呈现的文档(在 ⌥ 单击符号时的弹出窗口中，以及在快速帮助检查器 ⌥⌘2 中)。

符号文档注释现在基于相同的 Markdown syntax由丰富的 playground 注释使用，因此您可以在 Playgrounds 中执行的许多操作现在可以直接在源代码文档中使用。

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

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

更新

Xcode 7 测试版 4 ~ 添加了“- Throws: ...”作为顶级列表项，出现在参数旁边并返回快速帮助中的描述。

Xcode 7 测试版 1 ~ Swift 2 对语法的一些重大更改 - 现在基于 Markdown 的文档注释(与 Playgrounds 相同)。

Xcode 6.3 (6D570) ~ 缩进的文本现在被格式化为代码块，随后的缩进被嵌套。似乎不可能在这样的代码块中留下空行 - 尝试这样做会导致文本被添加到最后一行的末尾，其中包含任何字符。

Xcode 6.3 测试版 ~ 现在可以使用反引号将内联代码添加到文档注释中。

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)

评论风格

两者 /// (内联)和 /** */支持(块)样式注释来生成文档注释。虽然我个人更喜欢/** */的视觉风格注释，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)
///    }

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

内联元素

强调(斜体):

/// 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 可以是 Web URL(使用“http://”)或绝对文件路径 URL(我似乎无法获得相对文件路径)。

链接和图像的 URL 也可以与内联元素分开，以便将所有 URL 保存在一个可管理的地方:

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

关键词

除了 Markdown 格式之外，Xcode 还识别其他标记关键字以在快速帮助中突出显示。这些标记关键字大多采用 - <keyword>: 格式(异常(exception)是 parameter ，它也包括冒号前的参数名称)，其中关键字本身可以用大写/小写字符的任意组合编写。

符号部分关键字

以下关键字在帮助查看器中显示为突出部分，位于“说明”部分下方和“声明于”部分上方。包含时，它们的顺序固定如下所示，即使您可以在评论中以任何您喜欢的顺序包含它们。

请参阅 Symbol Section Commands section of the Markup Formatting Reference 中完整记录的部分关键字及其预期用途列表。 .

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

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

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

符号 描述 字段关键字

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

完整列表转述自 this excellent blog article通过埃丽卡萨顿。另请参阅 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 文档(旨在模仿 Apple 自己的文档)可以使用 Jazzy 从内联文档中生成。 ，一个开源命令行实用程序。

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

控制台示例取自 this NSHipster article