Swift standard documentation comment

Question

Is there a standard way to write documentation comment in the Swift language? Something equivalent to javadoc (Java) or docstrings (Python)?

example:

Answer 1

EDIT: This solution doesn't work with Swift 2.0.

OLDER solution work until swift 1.2:
I am now trying out the swift language and documentation tool. The Xcode is very sensitive to indent the text. The keywords must start at the same place. The keywords must insert beetwen colon, example ":returns:" If the xcode is not recognized the keyword, then Xcode puts the text into the description.

From this:

    /**
    Keresés után le lehet kérdezni egy konkrét találatot, pl. ha a harmadikra vagyunk mondjuk kíváncsiak.

    :note: n-1 legyen az \p index értéke, mert tömb révén a 0. elemmel keződik a tömb.
    :param: aSearchName Keresés meghatározásánál megadott név.
    :returns:               Konkrét találat. Ha nincs találat, akkor üres stringgel tér vissza a függvégy.
    :pre:               `aSearchName` != nil && !\p aSearchName != ""
    */

it will be:

Answer 2

I believe Apple is still changing the syntax. It looks like all the @ keywords are not implemented as of Xcode 6b2, but otherwise it's the same as ObjC.

So something like what you have would work:

/**
 * I am a function.
 */
func randomFn() {}

Although it seems that Swift stops to align the *s. Of course, you don't really need the stars except the first and last, so you can do this:

/*
  I am a function.
 */
func randomFn() {}

Both will be picked up by the comment parser so when you 3-finger click on the function name you will see its doc.

@param, @return worked for beta1 but not beta2, and those keywords crash the parser a lot in beta1, suggesting that Apple is not done with implementing those yet.

Answer 3

You can see actual documentation standard here: http://nshipster.com/swift-documentation/

Example:

/**
    Lorem ipsum dolor sit amet.

    - parameter bar: Consectetur adipisicing elit.

    - returns: Sed do eiusmod tempor.
*/

That works for me. Xcode 7.2

Answer 4

There are two types of Documentation comments single line "///..." and multiline "/**...*/" documentations NSHipster explains it here

Sample code copied from the website:

/**
    Repeats a string `times` times.

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

    - Throws: `MyError.InvalidTimes` if the `times` parameter 
      is less than zero.

    - Returns: A new string with `str` repeated `times` times.
*/

func repeatString(str: String, times: Int) throws -> String {
    guard times >= 0 else { throw MyError.InvalidTimes }
    return Repeat(count: 5, repeatedValue: "Hello").joinWithSeparator("")
}

Answer 5

Yes there is.

Swift includes "///" comment handling (although probably not everything yet).

Write something like:

/// Hey!
func bof(a: Int) {

}

Then option-click on the func name and voilà :)