Swift有文档生成支持吗?


238

许多语言都支持文档注释,以允许生成器(如javadocdoxygen)通过解析相同的代码来生成代码文档。

Swift是否有像这样的任何类型文档注释功能?


知道使用Objective-C的Xcode可以进行文档注释,我相信Apple会在不久的将来迅速将这个选项添加到Xcode中(但是,这只是一个假设,我没有证据)
Garoal 2014年

@Δdeveloper我猜也是一样,但是由于我没有看到任何参考,我想知道是否有人可以确认它,以及是否会有任何特定的文档工具。
pconcepcion 2014年

1
他们肯定会在将来添加一些东西,// MARK:注释也计划在将来的Xcode版本中使用。
Leandros 2014年

Doxygen风格的注释是类方法的工作,有很多警告。我将继续使用Doxygen样式(就像我对Obj-C所做的那样),并希望Xcode改善对这些样式的支持。
Pascal 2014年

1
有关记录块参数的信息,请参见stackoverflow.com/a/41970146/1054573
Leonard Pauli'2

Answers:


386

Xcode本身支持文档注释,可在快速帮助中(在单击符号时在弹出窗口中以及在快速帮助检查器中⌥⌘2)生成智能呈现的文档。

现在,符号文档注释基于丰富的游乐场注释所使用的Markdown语法,因此,您可以在游乐场中执行的许多操作现在都可以直接在源代码文档中使用。

有关语法的完整详细信息,请参见《标记格式参考》。请注意,丰富的游乐场注释和符号文档的语法之间存在一些差异。这些在文档中指出(例如,块引用只能在操场上使用)。

下面是一个示例以及当前可用于符号文档注释的语法元素列表。


更新

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文档快速帮助


Swift 2的语法(基于Markdown


评论风格

支持///(内联)和/** */(块)样式的注释,以生成文档注释。虽然我个人更喜欢/** */注释的视觉样式,但是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文章的控制台示例


1
看起来行为在Xcode 6.3的最终版本(6D570)中已更改。缩进的块现在被格式化为代码块,并且可以嵌套两个以上的级别。
NexD。

2
非常好的Swift 2.0文档语法描述。您应该更新帖子,以包括/// - todo: keyword
Leonardo

2
@uchuugaka其实没有。它可能以前基于reStructuredText,但是从Xcode 7开始,文档注释基于Markdown,其基本格式与运动场注释相同。有关详细信息,请参见Xcode 7发行说明
Stuart

2
有没有办法像JavaDoc一样链接到同一文件中的其他函数?例如,“查看myOtherMethod(param1:)扩展功能”
Ben Leggiero

1
@BenLeggiero,是的,使用/// - Tag: otherMethod[otherMethod](x-source-tag://otherMethod)。有关更多详细信息,请参见我的回答
克莱·埃利斯,

58

以下是一些可用于在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";
    }
}

上面显示的是快速帮助中的内容,与格式化的数字列表,项目符号点,参数和返回值文档一样。

这些都没有记录在案-提交雷达帮助他们。


2
马特•汤普森(Mattt Thompson)就此发表了一篇文章,他认为这是事实reStructuredText
Eonil 2014年

在上面的示例中,除了显示的星号之外,加号(+)和减号(-)还将用作项目符号。
文斯·奥沙利文

似乎///在任何解释性文本和:param:或之间必须有一个空白的注释()行:returns:。忽略这一点会使XCode(在编写本文时为6.1.1)在功能描述的主体中包含参数help。
罗宾·马查格

不幸的是,这不适用于Xcode 7 Beta。希望他们会在发行版本中修复它。
stevo.mit 2015年


41

Xcode 8的新增功能,您可以选择这样的方法

func foo(bar: Int) -> String { ... }

然后按command+ option+/或从Xcode的“编辑器”菜单中选择“结构”-“添加文档”,它将为您生成以下注释模板:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>

谢谢你 我只会提到您指出的键盘快捷键似乎不适用于丹麦语键盘,其中“ /”为shift-“ 7”。
RenniePet '16


11

我可以确认ShakenManChild提供了peopr解决方案

只要确定,说明下方会有一个空行!

无效情况

合适的方式

其他方式

另一种评论风格


8

是。基础通用(我用与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#>.
*/


6

我发现了一些有趣的东西,挖掘了Xcode二进制文件。以结尾的文件.swiftdoc。它肯定具有文档,因为这些文件包含Swift UIKit / Foundation API的文档,不幸的是,它似乎是专有文件格式,可以在Xcode的Documentation Viewer中使用。




-1

留意一下AppleDoc或Apple自己的HeaderDoc,这不是一个好主意,这是一个好主意。我仍然可以在10.9 Mavericks终端(headerdoc2html)中找到一些HeaderDoc提示。

我建议阅读最新的“ Xcode的新功能 ” *(不确定它是否仍在NDA中)*指向Xcode 5.1版本的链接也包含有关HeaderDoc的信息。


-1

从Xcode 5.0开始,支持Doxygen和HeaderDoc结构化注释。

资源


1
好吧,我在这种情况下问的是Swift。
pconcepcion 2014年

@pconcepcion您是否在Xcode中使用Swift?好的。
Matt Zanchelli 2014年

1
Matt,据我所知(我可能是错的),直到Xcode 6 beta才支持它Swift,所以我不确定Xcode 5的文档是否对Xcode 6(以及随后的Swift)有效
pconcepcion

@pconcepcion它有效。我一直在使用与Objective-C中相同的样式doxygen文档,并且该文档有效。上述方法或属性,我使用/// This is what the method does.
马特Zanchelli

好的,那就是您已经在Xcode 6上对其进行了测试。我很困惑,因为您在谈论Xcode 5,并且该链接用于Xcode 5
pconcepcion 2014年
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.