Swift是否有文档评论或工具？ [英] Does Swift have documentation comments or tools?
问题描述
许多语言支持文档注释以允许生成器（例如 javadoc 或）
评论风格
/// （inline）和 / ** * / （块）样式注释支持生成文档注释。虽然我个人更喜欢视觉风格的 / ** * / 评论，Xcode的自动缩进可以在复制/粘贴时消除这种注释风格的格式，因为它会删除前导空格。例如：
/ **
请参阅示例用法：
let x =方法（blah）
* /
粘贴时，代码块缩进被删除，不再作为代码呈现：
/ **
请参阅示例用法：
let x = method（blah）
* /
因此，我通常使用 /// ，并将在此答案中用于其余的示例。
块元素
标题：
///＃我的标题
或
///我的标题
/// ==========
副标题
/// ##我的小标题
或
///我的子目录
/// -------------
H水平规则：
/// ---
无序（项目符号）列表：
/// - 项目
/// - 另一项
您还可以对无序列表使用 + 或 * ，它必须是一致的。 / p>
有序（编号）列表：
/// 1.项目1
/// 2.项目2
/// 3.项目3
代码块：
/// for array {
/// print（item）
///}
需要至少四个空格的缩进。
内联元素
强调（斜体）：
///添加像* this *，或像_this_。
强（粗体）： p>
///你可以**真的让文字__strong__。
请注意，您不能混合星号（ * ）和下划线（ _ ）。
内联代码：
///调用`exampleMethod（_ :)`来演示内联代码。
链接：
/// [链接文本]（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>：（异常是参数，其中还包括参数
符号部分关键字
以下关键字显示在帮助查看器中的说明部分下方以及已声明的部分之上的突出部分。包含在内的订单如下所示，即使您可以按照您在评论中所喜欢的顺序包含它们，它们的订单也是如下所示。
请参阅完整的文档列表关键字及其预期用途在标记格式参考的符号部分命令部分。
/// - 参数：
/// - < #parameter name＃> ;:
/// - < #parameter name＃> ;:
/// - throws：
/// - 返回：
或者，您可以这样写每个参数：
/// - 参数< #parameter name＃> ;:
符号说明字段关键字
以下关键字列表显示为粗体标题身体的描写帮助查看器部分。他们将按照您所写的任何顺序出现，与说明部分的其余部分一样。
完整列表从这本优秀的博客文章由Erica Sadun。还可以在标记格式参考的符号说明字段命令部分。
归因： p>
/// - 作者：
/// - 作者：
/// - 版权所有：
/// - date：
可用性：
/// - since：
/// - version：
警告：
/// - 注意：
/// - important：
/// - note：
/// - comment：
/// - warning：
开发状态：
/// - bug：
/// - todo：
/// - 实验：
实施素质：
/// - 复杂性：
功能语义：
/// - precondition：
/// - postcondition：
/// - require：
/// - invariant：
交叉参考：
/// - seealso：
导出文档
HTML文档可以使用 Jazzy （一种开放源码的命令行工具）从内联文档生成模拟Apple自己的文档。
$ [sudo] gem install jazzy
$ jazzy
运行xcodebuild
解析...
建筑工地
堵塞♪♫到你新的新文件在`docs`
从这个NSHipster文章获取的控制台示例
Many languages support documentation comments to allow a generator (like javadoc or doxygen), generate the code documentation by parsing the same code.
Does Swift have any type documentation comments or documentation generation tools?
Documentation comments are supported natively in Xcode, producing smartly rendered documentation in Quick Help (both in the popover when ⌥-clicking symbols, and in the Quick Help Inspector ⌥⌘2).
Symbol documentation comments are now based on the same Markdown syntax used by rich playground comments, so a lot of what you can do in playgrounds can now be used directly in source code documentation.
For full details of the syntax, see Markup Formatting Reference. Note that there are some discrepancies between the syntax for rich playground comments & symbol documentation; these are pointed out in the document (e.g. block quotes can only be used in playgrounds).
Below is an example and a list of the syntax elements that currently work for symbol documentation comments.
Updates
Xcode 7 beta 4 ~ Added "- Throws: ..." as a top-level list item which appears alongside parameters and return descriptions in Quick Help.
Xcode 7 beta 1 ~ Some significant changes to syntax with Swift 2 - documentation comments now based on Markdown (same as playgrounds).
Xcode 6.3 (6D570) ~ Indented text is now formatted as code blocks, with subsequent indentations being nested. It doesn't appear to be possible to leave a blank line in such a code block - trying to do so results in the text being tacked onto the end of the last line with any characters in it.
Xcode 6.3 beta ~ Inline code can now be added to documentation comments using backticks.
Example for 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."
}
Syntax for Swift 2 (based on Markdown)
Comment Style
Both /// (inline) and /** */ (block) style comments are supported for producing documentation comments. While I personally prefer the visual style of /** */ comments, Xcode's automatic indentation can ruin formatting for this comment style when copying/pasting as it removes leading whitespace. For example:
/**
See sample usage:
let x = method(blah)
*/
When pasting, the code block indentation is removed and it is no longer rendered as code:
/**
See sample usage:
let x = method(blah)
*/
For this reason, I generally use ///, and will use it for the rest of the examples in this answer.
Block Elements
Heading:
/// # My Heading
or
/// My Heading
/// ==========
Subheading:
/// ## My Subheading
or
/// My Subheading
/// -------------
Horizontal rule:
/// ---
Unordered (bulleted) lists:
/// - An item
/// - Another item
You can also use + or * for unordered lists, it just has to be consistent.
Ordered (numbered) lists:
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Code blocks:
/// for item in array {
/// print(item)
/// }
An indentation of at least four spaces is required.
Inline Elements
Emphasis (italics):
/// Add like *this*, or like _this_.
Strong (bold):
/// You can **really** make text __strong__.
Note that you cannot mix asterisks (*) and underscores (_) on the same element.
Inline code:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Links:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Images:
/// 
The URL can be either a web URL (using "http://") or an absolute file path URL (I can't seem to get relative file paths to work).
The URLs for links and images can also be separated from the inline element in order to keep all URLs in one, manageable place:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Keywords
In addition to the Markdown formatting, Xcode recognises other markup keywords to display prominently in Quick Help. These markup keywords mostly take the format - <keyword>: (the exception is parameter, which also includes the parameter name before the colon), where the keyword itself can be written with any combination of uppercase/lowercase characters.
Symbol Section keywords
The following keywords are displayed as prominent sections in the help viewer, below the "Description" section, and above the "Declared In" section. When included, their order is fixed as displayed below even though you can include them in whatever order you like in your comments.
See the fully documented list of section keywords and their intended uses in the Symbol Section Commands section of the Markup Formatting Reference.
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Alternatively, you can write each parameter this way:
/// - parameter <#parameter name#>:
Symbol Description Field keywords
The following list of keywords are displayed as bold headings in the body of the "Description" section of the help viewer. They will appear in whatever order you write them in, as with the rest of the "Description" section.
Full list paraphrased from this excellent blog article by Erica Sadun. Also see the fully documented list of keywords and their intended uses in the Symbol Description Field Commands section of the Markup Formatting Reference.
Attributions:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Availability:
/// - since:
/// - version:
Admonitions:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Development State:
/// - bug:
/// - todo:
/// - experiment:
Implementation Qualities:
/// - complexity:
Functional Semantics:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Cross Reference:
/// - seealso:
Exporting Documentation
HTML documentation (designed to mimic Apple's own documentation) can be generated from inline documentation using Jazzy, an open-source command-line utility.
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Console example taken from this NSHipster article
这篇关于Swift是否有文档评论或工具？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
