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

Question

There is this great article by Nate Cook and Mattt Thompson that describes the format of documentation comments in Swift.

However, since Swift 2 in XCode 7 beta some parts of it do not seem to work any more. For example :param: and :returns: do not produce desired result (they are simply rendered as-is instead).

Other parts seem do keep working, though (i.e. both types of comments in /// ... or /** ... */ style, code-blocks, lists), but no way to mark up the documentation into similar sections like the core API has.

Does someone know if there is a way to highlight method parameters and returned results (what :param: and :returns: did in the past) in documentation comments in Swift 2?

Answer 1

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

Answer 2

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.