Свидетельство о быстрой документации по Swift

Существует ли стандартный способ написания комментария документации на языке Swift? Что-то эквивалентное javadoc (Java) или docstrings (Python)?

Пример:

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

Ответ 1

Да, есть.

Swift включает обработку комментариев "///" (хотя, вероятно, еще не все).

Напишите что-то вроде:

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

}

Затем нажмите на имя func и нажмите кнопку:)

Ответ 2

Существует два типа Документация одиночная строка "///..." и многострочная документация "/**...*/" NSHipster объясняет это здесь

Пример кода, скопированного с веб-сайта:

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

Ответ 3

EDIT: это решение не работает с Swift 2.0.

Решение OLDER работает до Swift 1.2:
Теперь я пытаюсь использовать быстрый инструмент языка и документации. Xcode очень чувствителен к отступу текста. Ключевые слова должны начинаться в одном месте. Ключевые слова должны вставлять beetwen colon, например ": returns:" Если xcode не распознается ключевым словом, тогда Xcode помещает текст в описание.

Из этого:

    /**
    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 != ""
    */

это будет:

Ответ 4

Я не думаю, что Swift поддерживает это. По крайней мере, это нигде не упоминалось.

Ответ 5

Я считаю, что Apple все еще меняет синтаксис. Похоже, что все ключевые слова @не реализованы как Xcode 6b2, но в остальном это то же самое, что и ObjC.

Так что-то вроде того, что у вас есть, будет работать:

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

Хотя кажется, что Swift перестает выравнивать * s. Конечно, вам не нужны звезды, кроме первого и последнего, поэтому вы можете сделать это:

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

Оба будут подхватываться парсером комментариев, поэтому, когда вы нажмете 3-значное имя функции, вы увидите его документ.

@param, @return работал для бета-1, но не для бета2, и эти ключевые слова сильно ломают парсер в бета-версии 1, предполагая, что Apple еще не реализована с их внедрением.

Ответ 6

Здесь вы можете увидеть фактический стандарт документации: http://nshipster.com/swift-documentation/

Пример:

/**
    Lorem ipsum dolor sit amet.

    - parameter bar: Consectetur adipisicing elit.

    - returns: Sed do eiusmod tempor.
*/

Это работает для меня. Xcode 7.2