Swift标准文档评论

Question

有没有一种标准的方法来编写Swift语言的文档注释？等同于javadoc（Java）或docstrings（Python）的东西？

示例：

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

Answer 1

是的。

Swift包含“///”评论处理（尽管可能还不是所有内容）。

写下类似的内容：

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

}

然后选择 - 点击func名称并发表声音：）

Answer 2

有两种类型的文档评论单行＆＃34; ///..."和多线＆＃34; /**...*/"文件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("")
}

Answer 3

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

OLDER解决方案一直工作到swift 1.2：
我现在正在尝试快速的语言和文档工具。 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 != ""
    */

它将是：

Answer 4

我不认为Swift支持这一点。至少在任何地方都没有提到它。

Answer 5

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

所以你所拥有的东西会起作用：

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

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

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

两个都将被评论解析器选中，所以当您用3个手指点击函数名称时，您将看到它的文档。

@param，@ return为beta1而不是beta2工作，这些关键字在beta1中大大破坏了解析器，这表明Apple还没有完成那些实现。

Answer 6

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

示例：

/**
    Lorem ipsum dolor sit amet.

    - parameter bar: Consectetur adipisicing elit.

    - returns: Sed do eiusmod tempor.
*/

这对我有用。 Xcode 7.2