Swift有文档注释或工具吗？

概述许多语言支持文档注释以允许生成器(如javadoc或 doxygen)，通过解析相同的代码生成代码文档。 Swift有任何类型的文档注释或文档生成工具吗？ 文档注释在Xcode中原生支持，在快速帮助中生成智能呈现文档(在咔嗒按钮符号和快速帮助检查器⌥⌘2中的d出框中)。 符号文档注释现在基于同样的Markdown syntax使用丰富的 *** 场注释，所以很多你可以在 *** 场中做的现在可以直接在源代码文档中 许多语言支持文档注释以允许生成器(如javadoc或 doxygen)，通过解析相同的代码生成代码文档。

Swift有任何类型的文档注释或文档生成工具吗？

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

符号文档注释现在基于同样的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$ jazzyRunning xcodebuildParsing ...building sitejam out ♪♫ to your fresh new docs in `docs`

控制台示例取自this NSHipster article

总结

以上是内存溢出为你收集整理的Swift有文档注释或工具吗？全部内容，希望文章能够帮你解决Swift有文档注释或工具吗？所遇到的程序开发问题。

如果觉得内存溢出网站内容还不错，欢迎将内存溢出网站推荐给程序员好友。