В Xcode 11 Apple представила мощную функцию под названием Swift Markup, которая позволяет разработчикам писать обширную документацию в своем коде Swift. Эту документацию можно легко визуализировать и отобразить как часть панели быстрой помощи Xcode или экспортировать в различные форматы. В этой статье мы рассмотрим различные методы использования Swift Markup в Xcode 11, а также приведем примеры кода для демонстрации каждого подхода.

1. Однострочные комментарии к документации:
   Однострочные комментарии к документации создаются с использованием трех косых черт (///), за которыми следует комментарий. Эти комментарии можно разместить над объявлением, чтобы дать краткое описание кода.

Пример:

/// This function calculates the sum of two integers.
func calculateSum(a: Int, b: Int) -> Int {
    return a + b
}

2. Многострочные комментарии к документации:
   Многострочные комментарии к документации заключаются между парой косых черт и звездочек (/… */) и могут занимать несколько строк. Эти комментарии обычно используются для предоставления более подробных пояснений, описаний параметров, описаний возвращаемых значений и примеров использования.

Пример:

/
 Calculates the sum of two integers.
 - Parameters:
    - a: The first integer.
    - b: The second integer.
 - Returns: The sum of the two integers.
 */
func calculateSum(a: Int, b: Int) -> Int {
    return a + b
}

3. Форматирование разметки.
   Swift Markup поддерживает различные параметры форматирования, повышающие читабельность и организацию вашей документации. Некоторые часто используемые параметры форматирования включают:

• Заголовки:

  /// # Heading

• Списки:

  /// - Item 1
  /// - Item 2

• Ссылки:

  /// Visit [Apple's website](https://www.apple.com) for more information.

• Блоков кода:

  /// ```
  /// let greeting = "Hello, World!"
  /// print(greeting)
  /// ```

4. Пользовательские теги разметки.
   Swift Markup позволяет создавать собственные теги для предоставления дополнительного контекста или категоризации вашей документации. Теги заключаются в угловые скобки (<>).

Пример:

/
 This function calculates the sum of two integers.
 - Parameters:
    - a: The first integer.
    - b: The second integer.
 - Returns: The sum of the two integers. <Tag: Mathematical Operation>
 */
func calculateSum(a: Int, b: Int) -> Int {
    return a + b
}