Swift有文档注释或工具吗?

前端之家收集整理的这篇文章主要介绍了Swift有文档注释或工具吗?前端之家小编觉得挺不错的,现在分享给大家,也给大家做个参考。
许多语言支持文档注释以允许生成器(如javadoc或 doxygen),通过解析相同的代码生成代码文档。

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

  1. /// Text like this appears in "Description".
  2. ///
  3. /// Leave a blank line to separate further text into paragraphs.
  4. ///
  5. /// You can use bulleted lists (use `-`,`+` or `*`):
  6. ///
  7. /// - Text can be _emphasised_
  8. /// - Or **strong**
  9. ///
  10. /// Or numbered lists:
  11. ///
  12. /// 7. The numbers you use make no difference
  13. /// 0. The list will still be ordered,starting from 1
  14. /// 5. But be sensible and just use 1,2,3 etc…
  15. ///
  16. /// ---
  17. ///
  18. /// More Stuff
  19. /// ==========
  20. ///
  21. /// Code
  22. /// ----
  23. ///
  24. /// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block,handy for example usage:
  25. ///
  26. /// // Create an integer,and do nothing with it
  27. /// let myInt = 42
  28. /// doNothing(myInt)
  29. ///
  30. /// // Also notice that code blocks scroll horizontally instead of wrapping.
  31. ///
  32. /// Links & Images
  33. /// --------------
  34. ///
  35. /// Include [links](https://en.wikipedia.org/wiki/Hyperlink),and even images:
  36. ///
  37. /// ![Swift logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
  38. ///
  39. /// - note: That "Note:" is written in bold.
  40. /// - requires: A basic understanding of Markdown.
  41. /// - seealso: `Error`,for a description of the errors that can be thrown.
  42. ///
  43. /// - parameters:
  44. /// - int: A pointless `Int` parameter.
  45. /// - bool: This `Bool` isn't used,but its default value is `false` anyway…
  46. /// - throws: A `BadLuck` error,if you're unlucky.
  47. /// - returns: Nothing useful.
  48. func doNothing(int: Int,bool: Bool = false) throws -> String {
  49. if unlucky { throw Error.BadLuck }
  50. return "Totally contrived."
  51. }

Swift 2的语法(基于Markdown)

注释样式

支持生成文档注释的///(inline)和/ ** * /(block)样式注释。虽然我个人喜欢/ ** * /评论的视觉风格,Xcode的自动缩进可以破坏这个评论样式的复制/粘贴的格式,因为它删除了前导空格。例如:

  1. /**
  2. See sample usage:
  3.  
  4. let x = method(blah)
  5. */

粘贴时,代码块缩进将被删除,并且不再显示代码

  1. /**
  2. See sample usage:
  3.  
  4. let x = method(blah)
  5. */

出于这个原因,我一般使用///,并将其用于本回答中的其余示例。

块元素

标题

  1. /// # My Heading

要么

  1. /// My Heading
  2. /// ==========

标题

  1. /// ## My Subheading

要么

  1. /// My Subheading
  2. /// -------------

水平尺:

  1. /// ---

无序(项目符号)列表:

  1. /// - An item
  2. /// - Another item

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

有序(编号)列表:

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

代码块:

  1. /// for item in array {
  2. /// print(item)
  3. /// }

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

内联元素

强调(斜体):

  1. /// Add like *this*,or like _this_.

强(粗体):

  1. /// You can **really** make text __strong__.

请注意,不能在同一元素上混合星号(*)和下划线(_)。

内联代码

  1. /// Call `exampleMethod(_:)` to demonstrate inline code.

链接

  1. /// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)

图片

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

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

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

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

关键词

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

  1. /// - parameters:
  2. /// - <#parameter name#>:
  3. /// - <#parameter name#>:
  4. /// - throws:
  5. /// - returns:

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

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

符号说明字段关键字

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

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

归属:

  1. /// - author:
  2. /// - authors:
  3. /// - copyright:
  4. /// - date:

可用性:

  1. /// - since:
  2. /// - version:

警告:

  1. /// - attention:
  2. /// - important:
  3. /// - note:
  4. /// - remark:
  5. /// - warning:

开发状态:

  1. /// - bug:
  2. /// - todo:
  3. /// - experiment:

实施质量:

  1. /// - complexity:

函数语义:

  1. /// - precondition:
  2. /// - postcondition:
  3. /// - requires:
  4. /// - invariant:

交叉参考:

  1. /// - seealso:

导出文档

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

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

控制台示例取自this NSHipster article

猜你在找的Swift相关文章