Видео и материалы

---

Люди всегда разрушают то, что любят больше всего.

В этом уроке

• Как делать документацию в Xcode
• Язык разметки MarkDown

---

Пишем комментарии к функциям

Допустим мы хотим создать документацию к функции, чтобы люди понимали, что же мы сотворили. Вот пример того, как это будет выглядеть в Swift:

///
/// Function does something
/// - parameter first: The first integer to add
/// - parameter second: The second integer to add
/// - returns: The sum of two integers
/// - throws: Fucking error
///

func myPlus(first: Int, second: Int) -> Int {
    return first + second
}

Теперь при нажатии левой кнопкой с зажатым alt появится вот такое милое окно, Вы видели его уже ранее в стандартных функциях Swift:

Разберём его подробнее:

1. Для создания документации мы использовали комментарии с тремя слешами ///
2. Первая и последняя строка комментариев (те, что пустые) необязательны, но повышают читаемость кода.
3. На первой значащей строке идёт описание функции. Оно может идти несколько строк. Это поле Description
4. Затем идёт несколько строк с описанием параметров. Используется конструкция - parameter @имя_параметра: @описание. Заметьте, что надо описывать не сигнатуру или тип параметра, а что он собственно означает.
5. Далее идёт конструкция - returns: - описание того, что возвращает функция.
6. - throws: какие ошибки по смыслу может бросить функция.

Если Вы нажмёте по фигурной скобке с зажатым CMD, то появится очень интересное меню:

Оно позволяет выполнять различные действия над блоком. Само меню контекстное, то есть его состав зависит от ситуации. Так как здесь идёт определение функции, то мы можем добавить параметр в функцию.
Нас же интересует сейчас кнопка Fold - она свернёт по нажатию участок кода, чтобы он не мешал Вам видеть другие части кода. Раньше этот функционал выносился на левую панель с номерами строк:

С помощью комбинации CMD + ALT + / можно создать блок комментариев на основе сигнатуры функции

---

MarkDown

Для всех этих дел мы использовали разметку markdown - она представляет собой упрощенный язык разметки:

• Она проще и лаконичнее HTML
• Однако она остаётся мощнее документов с формированием наподобие docx
• Этот формат переносим между платформами и удобно без потерь собирается в текстовые документы. Кроме того он легко всматривается в html и наоборот.

Мы в своей работе для текстов используем этот формат вместе с приложением Bear Writer, однако Вы просто можете создать файл в формате .md в Xcode.

Давайте изучим пару фишек MarkDown.

Чтобы поставить заголовок используйте значок # и через пробел напишите название заголовка, при этом увеличивая число знаков решетки мы увеличиваем уровень заголовка, что уменьшает его значимость. Есть 6 уровней заголовков:

# H1
## H2
### H3
#### H4
##### H5
###### H6

Также можно создать подчеркнутые заголовки H1 и H2 следующим образом:

ALT-H1
======

Alt-H2
------

Выглядеть это будет так:

Чтобы выделить текст:

• наклонным шрифтом используются символы * или _
• жирным шрифтом используются символы ** или __
• перечёркнутым шрифтом - ~~

*Italic* _italic_
**strong** __strong__
~~strikethrough~~

Чтобы создать списки можно использовать:

• Последовательный ввод чисел с точкой на конце для нумерованных списков, после которых через пробел пишется элемент
• Знаки *, -, +
• Списки могут быть вложенными, если начало нового списка написано через табуляцию или 4 (иногда 2) пробела

  1. First ordered list item
  2. Another item
      * Unordered sub-list.
      - Unordered
      + Unordered

Чтобы создать ссылку используется синтаксис: [отображаемый текст](ссылка):

[I'm a link](https://swiftworld.ru)

Для картинки ситуация аналогичная, разве что добавляется восклицательный знак:

![swift](https://swiftworld.ru/android-chrome-512x512.png)

Для подсветки кода можно использовать два стиля - inline, когда код подсвечивается в строке:

`let a = 1`

И многострочный, когда подсвечиваются блоки кода. В таком случае часто указывается название языка, чтобы интерпретатор разметки мог понять, о чём идёт речь:

```swift
let a = 1
a += 1 //2
```

В данном случае подсветки не происходит, так как интерепретатор markdown не знал о swift.

Для использования цитат нужен символ >:

> Весь мир - всего лишь игра

Горизонтальные линии ставятся с помощью - - - -:

- - - -

Мы рассмотрели здесь лишь самые основные пункты markdown - ибо к этому стандарту существует множество расширений и некоторые интерпретаторы ведут себя по-своему.

---