Swift 标准文档注释答案

【问题标题】：Swift standard documentation commentSwift 标准文档注释
【发布时间】：2014-06-08 15:17:21
【问题描述】：

有没有标准的方式来用 Swift 语言编写文档注释？相当于 javadoc (Java) 或 docstrings (Python) 的东西？

示例：

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

【问题讨论】：

见nshipster.com/swift-documentation
Does Swift have documentation comments or tools?的可能重复

标签： swift

【解决方案1】：

是的。

Swift 包括“///”注释处理（虽然可能还不是全部）。

这样写：

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

}

然后选项-单击函数名称，瞧:)

【讨论】：

这是正确的答案。 Ferenc Kiss 上面给出了部分答案。关键字，例如 :param: 和 :returns: 确实有效，但在 /// 内部。

【解决方案2】：

Documentation cmets有两种类型：单行“///...”和多行“/**...*/”文档NSHipster explains it here

从网站复制的示例代码：

/**
    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("")
}

【讨论】：

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

【解决方案3】：

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

旧的解决方案在 swift 1.2 之前有效：
我现在正在试用 swift 语言和文档工具。 Xcode 对缩进文本非常敏感。关键字必须从同一位置开始。关键字必须插入beetwen冒号，例如“: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 != ""
    */

它将是：

【讨论】：

这是部分答案。 /* */ 不起作用。关键字，如 :param:、:returns: 确实有效，但在 /// 内部，正如下面提到的 Jean Le Moignan。
以/** 而非/* 开头。
嗯，它对我有用。我从我的真实源代码创建了一个屏幕截图。非常重要的是，每一行的缩进都和“/**”一样！！！
那很重要。您必须使所有内容都在同一缩进级别对齐。它在缩进为一级时起作用。
我倾向于删除:note: 和:pre:，因为它们不是公认的关键字。您不妨使用:foo: 和:bar:。

【解决方案4】：

我相信 Apple 仍在改变语法。看起来所有的@关键字都没有在 Xcode 6b2 中实现，但除此之外它与 ObjC 相同。

所以像你所拥有的那样工作：

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

虽然 Swift 似乎停止对齐 *s。当然，除了第一个和最后一个，你并不需要星星，所以你可以这样做：

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

评论解析器会拾取两者，因此当您用三指点击函数名称时，您将看到它的文档。

@param，@return 适用于 beta1 但不适用于 beta2，这些关键字在 beta1 中使解析器崩溃了很多，这表明 Apple 还没有完成这些实现。

【讨论】：

【解决方案5】：

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

例子：

/**
    Lorem ipsum dolor sit amet.

    - parameter bar: Consectetur adipisicing elit.

    - returns: Sed do eiusmod tempor.
*/

这对我有用。 Xcode 7.2

【讨论】：