符号文档注释现在基于同样的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:
- ///
- /// 
- ///
- /// - 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)
图片:
- /// 
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> ;:(异常是参数,其还包括冒号之前的参数名称),其中关键字本身可以用大写/小写字符的任何组合来写。 符号节关键字 以下关键字在帮助查看器中的“说明”部分下方和“已声明的部分”上方显示为突出部分。如果包含,它们的顺序是固定的,如下所示,即使您可以按您喜欢的任何顺序包括在您的评论。 请参阅完全记录的部分关键字列表及其在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