Swift标准文档注释

Question

在Swift语言中，是否有一种标准的编写文档注释的方式？类似于Java中的javadoc或Python中的docstrings。

示例：

/**
 * My docstring example
 * @return the String "foo"
*/
func foo() -> String {
    return "Foo"
}

- Griffosx

---

请查看http://nshipster.com/swift-documentation/。 - Rob

可能是Swift是否有文档注释或工具？的重复问题。 - Kevin

Answer 1

有的。

Swift包含“///”注释处理（虽然可能还不完整）。

写出类似这样的东西：

/// Hey!
func bof(a: Int) {

}

然后在函数名上进行选项点击，就完成了 :)

- Jean Le Moignan

---

这是正确的答案。Ferenc Kiss在上面给出了部分答案。关键词，如 :param: 和 :returns: 可以工作，但只能在 /// 内使用。 - Sergey M

Answer 2

有两种类型的文档注释：单行 "///..." 和多行 "/**...*/" 文档 NSHipster 在这里解释了它

从网站上复制的示例代码：

/**
    Repeats a string `times` times.

    - Parameter str:   The string to repeat.
    - Parameter times: The number of times to repeat `str`.

    - Throws: `MyError.InvalidTimes` if the `times` parameter 
      is less than zero.

    - Returns: A new string with `str` repeated `times` times.
*/

func repeatString(str: String, times: Int) throws -> String {
    guard times >= 0 else { throw MyError.InvalidTimes }
    return Repeat(count: 5, repeatedValue: "Hello").joinWithSeparator("")
}

- Khaled Annajar

---

这是正确的答案。上面Jean的那个已经过时了。 - j3141592653589793238

Answer 3

编辑：此解决方案不适用于Swift 2.0。

旧的解决方案适用于Swift 1.2及以下版本：
我现在正在尝试使用Swift语言和文档工具。 Xcode对缩进文本非常敏感。关键字必须从同一位置开始。 关键字必须插入冒号之间，例如“:returns:” 如果Xcode无法识别关键字，则Xcode将文本放入描述中。

从这个开始：

    /**
    Keresés után le lehet kérdezni egy konkrét találatot, pl. ha a harmadikra vagyunk mondjuk kíváncsiak.

    :note: n-1 legyen az \p index értéke, mert tömb révén a 0. elemmel keződik a tömb.
    :param: aSearchName Keresés meghatározásánál megadott név.
    :returns:               Konkrét találat. Ha nincs találat, akkor üres stringgel tér vissza a függvégy.
    :pre:               `aSearchName` != nil && !\p aSearchName != ""
    */

它将会是：

（注：无需翻译的部分保留原文）

- feca

---

这是一个部分答案。/* */ 不起作用。关键字，例如 :param:，:returns: 起作用，但在 /// 内，正如 Jean Le Moignan 在下面提到的那样。 - Sergey M

请以 /** 开始注释，而不是 /*。 - feca

嗯，对我来说它有效。我从我的真实源代码中创建了一个截图。 非常重要的是，每一行缩进都与“/**”相同！！！ - feca

那是非常重要的一点。你必须让所有缩进保持在同一级别上。只有当缩进在一个级别时才能正常工作。 - Sergey M

我倾向于删除:note:和:pre:，因为它们不是被识别的关键词。你也可以使用:foo:和:bar:。 - Rob

Answer 4

您可以在此处查看实际文档标准： http://nshipster.com/swift-documentation/

示例：

/**
    Lorem ipsum dolor sit amet.

    - parameter bar: Consectetur adipisicing elit.

    - returns: Sed do eiusmod tempor.
*/

对我有用。Xcode 7.2

- Eldar Pikunov

Answer 5

我相信苹果公司仍在更改语法。据看，截止到Xcode 6b2，所有@关键字都没有实现，但除此之外它与ObjC相同。

因此，像您所拥有的这样的东西将会起作用:

/**
 * I am a function.
 */
func randomFn() {}

尽管看起来Swift停止对*进行对齐。当然，除了第一个和最后一个之外，您实际上并不需要这些星号，因此可以这样做：

/*
  I am a function.
 */
func randomFn() {}

这两个都将被注释解析器捕获，因此当您在函数名称上进行三指点击时，您将看到其文档。

@param、@return 在beta1中有效，但在beta2中无效，而且这些关键字在beta1中经常会导致解析器崩溃，这表明苹果公司尚未完成对它们的实现。

- danqing