Swift 4.1 / 1.2. 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 - она представляет собой упрощенный язык разметки:

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

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

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

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

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

ALT-H1
======

Alt-H2
------

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



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

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

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

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

[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 - ибо к этому стандарту существует множество расширений и некоторые интерпретаторы ведут себя по-своему.