什么是Swift 2中文档评论的新格式？ （XCode 7 beta 3）

Question

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

但是，由于XCode 7 beta中的Swift 2的某些部分似乎不再工作。例如，:param:和:returns:不会产生所需的结果（它们只是简单地呈现为原样）。

其他部分似乎仍然在继续工作（即/// ...或/** ... */样式，代码块，列表中的两种类型的注释），但没有办法将文档标记为类似的部分，如核心API。

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

Answer 1

如果您正在寻找Symbol Documentation Markup Syntax，这意味着如果您想知道使用Markdown为您的方法编写文档的新语法（Xcode 7），则可以在Apple网站上找到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 

Answer 2

What’s new in Xcode 7.给出了一个提示显示为丰富的快速帮助文本嵌入 图像和链接

降价的意见。

和Xcode的7测试版发行说明状态：

斯威夫特文档注释使用基于降价 格式的语法，具有丰富的操场评论对准他们。 （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("") 
} 

有关降价的更多信息，请参阅

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

和许多

• Playground Markup Format for Comments

应用于内联文档的意见为好。

例如，您可以添加

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

其中 “重要” 呈现强。

Answer 3

在Xcode中7 beta 4版本的参数列表只能写成这样：（这应该是对Martin R的帖子评论，但我没有信誉的话）

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