Swift 2 中文档注释的新格式是什么？ (XCode 7 测试版 3)

Question

Nate Cook 和 Mattt Thompson 的 great article 描述了 Swift 中文档注释的格式。

但是，自从 Swift 2 in XCode 7 beta 以来，它的某些部分似乎不再有效。例如 :param: 和 :returns: 不会产生预期的结果（它们只是按原样呈现）。

其他部分似乎确实在继续工作（即 /// ... 或 /** ... */ 风格的两种类型的评论、代码块、列表），但无法将文档标记为类似的API 等核心部分。

有人知道在 Swift 2 的文档注释中是否有办法突出显示方法参数和返回结果（:param: 和 :returns: 过去所做的）吗？

Answer 1

What’s new in Xcode 7.给出提示

Markdown comments shown as rich text in Quick Help with embedded images and links.

和 Xcode 7 beta 发行说明状态：

Swift documentation comments use a syntax based on the Markdown format, aligning them with rich comments in playgrounds. (20180161)

后跟简短说明。

例如，

/**
    Repeats a string `times` times.

    :param: str     The string to repeat.
    :param: times   The number of times to repeat `str`.

    :returns: A new string with `str` repeated `times` times.
*/
func repeatString(str: String, times: Int) -> String {
    return join("", Array(count: times, repeatedValue: str))
}

来自 http://nshipster.com/swift-documentation/ 的

现在将写为

/// Repeats a string `times` times.

/// - Parameters:
///     - str:     The string to repeat.
///     - times:   The number of times to repeat `str`.
/// - returns: A new string with `str` repeated `times` times.
func repeatString(str: String, times: Int) -> String {
   return Repeat(count: times, repeatedValue: str).joinWithSeparator("")
}

或多行注释：

/**
    Repeats a string `times` times.

    - Parameter str:   The string to repeat.
    - Parameter times: The number of times to repeat `str`.
    - returns: A new string with `str` repeated `times` times. 
*/
func repeatString(str: String, times: Int) -> String {
    return Repeat(count: times, repeatedValue: str).joinWithSeparator("")
}

有关 Markdown 的更多信息，请参阅

和大部分

Playground Markup Format for Comments

也适用于内联文档注释。

例如，您可以添加

     **Important:** `times` must not be negative.

渲染 "Important" 的地方 strong.

Answer 2

在Xcode7 beta 4中参数列表只能这样写：

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

（这应该是对 s post 的评论，但我没有这样做的声誉。）

Answer 3

如果您正在寻找 Symbol Documentation Markup Syntax，这意味着如果您想了解新语法 (Xcode 7) 以使用 Markdown 为您的方法编写文档，那么 Markup Formatting Reference 在苹果网站上。

这里是定义块评论的方法：

/**
  line of text with optional markup commands
  …
  line of text with optional markup commands
*/

下面是带有最重要标签的评论示例：

/**
  Just testing documentation using Markdown
  - returns: Bool
  - parameter param1:String
  - parameter param2:String
  - Throws: error lists
*/

这是短格式

/// line of text with optional markup commands

Swift 2 中文档注释的新格式是什么？ (XCode 7 测试版 3)

What is the new format of documentation comments in Swift 2? (XCode 7 beta 3)

documentation

comments

swift

xcode7

swift2