许多语言都支持文档注释,以允许生成器(如javadoc
或doxygen)通过解析相同的代码来生成代码文档。
Swift是否有像这样的任何类型文档注释功能?
// MARK:
注释也计划在将来的Xcode版本中使用。
许多语言都支持文档注释,以允许生成器(如javadoc
或doxygen)通过解析相同的代码来生成代码文档。
Swift是否有像这样的任何类型文档注释功能?
// MARK:
注释也计划在将来的Xcode版本中使用。
Answers:
Xcode本身支持文档注释,可在快速帮助中(在⌥单击符号时在弹出窗口中以及在快速帮助检查器中⌥⌘2)生成智能呈现的文档。
现在,符号文档注释基于丰富的游乐场注释所使用的Markdown语法,因此,您可以在游乐场中执行的许多操作现在都可以直接在源代码文档中使用。
有关语法的完整详细信息,请参见《标记格式参考》。请注意,丰富的游乐场注释和符号文档的语法之间存在一些差异。这些在文档中指出(例如,块引用只能在操场上使用)。
下面是一个示例以及当前可用于符号文档注释的语法元素列表。
Xcode 7 beta 4〜添加了“ - Throws: ...
”作为顶级列表项,它与参数并在快速帮助中返回说明一起显示。
Xcode 7 beta 1〜Swift 2对语法的一些重大更改-现在基于Markdown的文档注释(与游乐场相同)。
Xcode 6.3(6D570)〜缩进的文本现在被格式化为代码块,随后的缩进被嵌套。在这样的代码块中似乎不可能留空行-尝试这样做会导致文本被粘贴到最后一行的末尾,其中包含任何字符。
Xcode 6.3 beta〜内联代码现在可以使用反引号添加到文档注释中。
/// 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."
}
支持///
(内联)和/** */
(块)样式的注释,以生成文档注释。虽然我个人更喜欢/** */
注释的视觉样式,但是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也可以与inline元素分开,以便将所有URL放在一个易于管理的位置:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
除了Markdown格式外,Xcode还可以识别其他标记关键字,以在快速帮助中突出显示。这些标记关键字大多采用以下格式- <keyword>:
(例外是parameter
,该格式还包括冒号前面的参数名称),其中关键字本身可以使用大写/小写字符的任意组合来编写。
以下关键字在帮助查看器中的“描述”部分下方和“声明的位置”部分上方显示为突出显示的部分。当包含它们时,即使您可以按自己喜欢的顺序将它们包含在注释中,它们的顺序也如下所示固定。
请参见《标记格式参考》的“ 符号节命令”部分中完整记录的节关键字及其预期用途的列表。
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
另外,您可以这样编写每个参数:
/// - parameter <#parameter name#>:
以下关键字列表在帮助查看器的“描述”部分的正文中显示为粗体标题。它们将以您编写它们的任何顺序出现,与“描述”部分的其余部分一样。
完整列表摘自Erica Sadun的这篇出色的博客文章。另请参阅《标记格式参考》的“ 符号描述字段命令”部分中完整记录的关键字列表及其预期用途。
归因:
/// - author:
/// - authors:
/// - copyright:
/// - date:
可用性:
/// - since:
/// - version:
告诫:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
发展状况:
/// - bug:
/// - todo:
/// - experiment:
实施质量:
/// - complexity:
功能语义:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
交叉参考:
/// - seealso:
可以使用开源命令行实用工具Jazzy从内联文档中生成HTML文档(旨在模仿Apple自己的文档)。
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
摘自此NSHipster文章的控制台示例
/// - todo: keyword
myOtherMethod(param1:)
扩展功能”
以下是一些可用于在Xcode 6中记录快速代码的方法。它非常容易出错,并且对冒号敏感,但是总比没有好:
class Foo {
/// This method does things.
/// Here are the steps you should follow to use this method
///
/// 1. Prepare your thing
/// 2. Tell all your friends about the thing.
/// 3. Call this method to do the thing.
///
/// Here are some bullet points to remember
///
/// * Do it right
/// * Do it now
/// * Don't run with scissors (unless it's tuesday)
///
/// :param: name The name of the thing you want to do
/// :returns: a message telling you we did the thing
func doThing(name : String) -> String {
return "Did the \(name) thing";
}
}
上面显示的是快速帮助中的内容,与格式化的数字列表,项目符号点,参数和返回值文档一样。
这些都没有记录在案-提交雷达帮助他们。
reStructuredText
。
///
在任何解释性文本和:param:
或之间必须有一个空白的注释()行:returns:
。忽略这一点会使XCode(在编写本文时为6.1.1)在功能描述的主体中包含参数help。
Xcode 8的新增功能,您可以选择这样的方法
func foo(bar: Int) -> String { ... }
然后按command
+ option
+/
或从Xcode的“编辑器”菜单中选择“结构”-“添加文档”,它将为您生成以下注释模板:
/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>
Swift包含“ ///”注释处理(尽管可能还不是全部)。
写类似:
/// Hey!
func bof(a: Int) {
}
然后在函数名称和名称上单击鼠标右键:)
是。基础通用(我用与Obj-C相当的功能为其制作了摘录)
目标C:
/**
@brief <#Short description - what it is doing#>
@discussion <#Description#>
@param <#paramName#> <#Description#>.
@return <#dataType#> <#Description#>.
*/
迅速
/**
<#Short inline description - what it is doing#>
<#Description#>
:param: <#paramName#> <#Description#>.
:returns: <#dataType#> <#Description#>.
*/
如果您只使用Swift,那么Jazzy值得一看。
Jazzy可以帮助生成漂亮的苹果风格文档。这是一个示例应用程序,其中包含有关如何快速使用和配置的详细信息。
从Xcode 5.0开始,支持Doxygen和HeaderDoc结构化注释。
/// This is what the method does.
等