Каков новый формат комментариев к документации в Swift 2? (XCode 7 beta 3)

Эта статья отличная статья от Nate Cook и Mattt Thompson, которая описывает формат комментариев к документации в Swift.

Однако, поскольку Swift 2 в XCode 7 beta некоторые его части больше не работают. Например, :param: и :returns: не дают желаемого результата (они просто отображаются как-is вместо).

Другие части, похоже, продолжают работать (т.е. оба типа комментариев в стиле /// ... или /** ... */, кодовые блоки, списки), но не имеют возможности разметки документации в аналогичные разделы, такие как основной API,.

Кто-нибудь знает, есть ли способ выделить параметры метода и возвращенные результаты (что :param: и :returns: в прошлом) в комментариях к документации в Swift 2?

Ответ 1

Если вы ищете Symbol Documentation Markup Syntax, то есть, если вы хотите узнать новый синтаксис (Xcode 7) для написания документации для своих методов с помощью Markdown, есть "Ссылка на форматирование разметки" на веб-сайте Apple.

Здесь вы определяете Комментарий блока:

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

И вот пример комментария с наиболее важными тегами:

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

И вот короткий формат

/// line of text with optional markup commands

Ответ 2

Что нового в Xcode 7. дает подсказку

Комментарии Markdown, показанные в виде расширенного текста в Quick Help со встроенными изображений и ссылок.

и в примечаниях к бета-версии Xcode 7 указано:

В комментариях Swift документации используется синтаксис, основанный на Markdown формат, сопоставляя их с богатыми комментариями на игровых площадках. (20180161)

за которым следует краткое описание.

В качестве примера,

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

из http://nshipster.com/swift-documentation/ теперь будет написано как

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

Или с многострочным комментарием:

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

Для получения дополнительной информации о Markdown см.

и большая часть

Формат разметки игровой площадки для комментариев

применяется также к комментариям встроенной документации.

Например, вы можете добавить

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

где "Важное" отображается strong.

Ответ 3

В Xcode 7 beta 4 список параметров может быть записан только следующим образом:

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

(Это должен быть комментарий к Мартин R, но у меня нет репутации, чтобы сделать это.)