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:

/**
 * My docstring example
 * @return the String "foo"
*/
func foo() -> String {
    return "Foo"
}

Possible duplicate of [Does Swift have documentation comments or tools?](http://stackoverflow.com/questions/24047991/does-swift-have-documentation-comments-or-tools) — Kevin, Apr 09 '16 at 00:28

Jean Le Moignan · Answer 1 · 2014-06-11T20:28:35.097

19

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à :)

edited Jun 11 '14 at 20:28

answered Jun 11 '14 at 18:52

Jean Le Moignan

22,158
3
31
37

1

This is the right answer. **Ferenc Kiss** gave a partial answer above. Keywords, such as `:param:` and `:returns:` do work, but inside `///`. – Sergey M Dec 23 '14 at 18:58

score 18 · Answer 2 · answered Apr 26 '16 at 11:10

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

This is the correct answer. The one above by Jean is outdated. — j3141592653589793238, Jun 19 '19 at 10:49

feca · Answer 3 · 2015-06-17T07:29:41.577

2

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:

enter image description here

edited Jun 17 '15 at 07:29

answered Nov 26 '14 at 13:34

feca

1,119
16
14

That is a partial answer. `/* */` doesn't work. Keywords, such as `:param:`, `:returns:` do work, but inside `///` as **Jean Le Moignan** mentioned below. – Sergey M Dec 23 '14 at 18:57
Begin with `/**` not `/*`. – feca Dec 25 '14 at 14:30
1

Hm, it works for me. I created a screenshot from my real sourcecode. It is very important, that every line indent is same like "/**"!!! – feca Dec 27 '14 at 09:12
That was very important one. You have to have everything aligned at the same level of indentation. It works when the indentation is at one level. – Sergey M Dec 29 '14 at 06:12
2

I'd be inclined to remove `:note:` and `:pre:` because those are not recognized keywords. You might as well have used `:foo:` and `:bar:`. – Rob Jan 18 '15 at 17:19

score 0 · Answer 4 · answered Jun 30 '14 at 07:03

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.

score 0 · Answer 5 · answered Jan 26 '16 at 20:39

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

Swift standard documentation comment

5 Answers5

Linked

Related