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

If you're looking for Symbol Documentation Markup Syntax, meaning if you want to know the new syntax (Xcode 7) to write documentation for your methods using Markdown, there is the Markup Formatting Reference on Apple's website.

Here's how you define a Block Comment :

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

And here's an example of a comment with the most important tags :

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

And here's the short format

/// line of text with optional markup commands

What’s new in Xcode 7. gives a hint

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

and the Xcode 7 beta release notes state:

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

followed by a short description.

As an example,

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

from http://nshipster.com/swift-documentation/ would now be written as

/// 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("")}

Or with multiline comment:

/**    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("")}

For more information on Markdown, see

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

and much of

• Playground Markup Format for Comments

applies to inline documentation comments as well.

For example, you could add

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

where "Important" is rendered strong.

In Xcode 7 beta 4 a list of parameters can only be written like this:

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

(This should be a comment on Martin Rs post but I don't have the reputation to do so.)