什麼是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`.