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

Question

Nate Cook和Mattt Thompson 撰写的这篇伟大的文章描述了Swift中文档注释的格式.

但是,自从XCode 7测试版中的Swift 2以来,它的某些部分似乎不再起作用了.例如,:param:并且:returns:不会产生所需的结果(它们只是按原样呈现).

其他部分似乎仍然可以继续工作(即两种类型的注释/// ...或/** ... */样式,代码块,列表),但无法将文档标记为类似于核心API的类似部分.

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

Answer 1

如果您正在寻找Symbol Documentation Markup Syntax,这意味着如果您想知道使用Markdown为您的方法编写文档的新语法(Xcode 7), Apple的网站上就有标记格式参考.

以下是定义块注释的方法:

/**
  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

Answer 2

Xcode 7中的新功能给出了一个提示

Markdown注释在快速帮助中显示为带有嵌入图像和链接的富文本.

和Xcode 7测试版发行说明:

Swift文档注释使用基于Markdown格式的语法,将它们与游乐场中的丰富注释对齐.(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的更多信息,请参阅

• https://en.wikipedia.org/wiki/Markdown
• http://daringfireball.net/projects/markdown/

而且很多

• 注释的游乐场标记格式

也适用于内联文档注释.

例如,您可以添加

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

其中"重要"变得强大.