Люди всегда разрушают то, что любят больше всего.
Допустим мы хотим создать документацию к функции, чтобы люди понимали, что же мы сотворили. Вот пример того, как это будет выглядеть в 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:
Разберём его подробнее:
///
Description
- parameter @имя_параметра: @описание
. Заметьте, что надо описывать не сигнатуру или тип параметра, а что он собственно означает.- returns:
- описание того, что возвращает функция.- throws:
какие ошибки по смыслу может бросить функция.Если Вы нажмёте по фигурной скобке с зажатым CMD, то появится очень интересное меню:
Оно позволяет выполнять различные действия над блоком. Само меню контекстное, то есть его состав зависит от ситуации. Так как здесь идёт определение функции, то мы можем добавить параметр в функцию.
Нас же интересует сейчас кнопка Fold
- она свернёт по нажатию участок кода, чтобы он не мешал Вам видеть другие части кода. Раньше этот функционал выносился на левую панель с номерами строк:
С помощью комбинации CMD + ALT + / можно создать блок комментариев на основе сигнатуры функции
Для всех этих дел мы использовали разметку markdown
- она представляет собой упрощенный язык разметки:
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~~
Чтобы создать списки можно использовать:
*
, -
, +
1. First ordered list item
2. Another item
* Unordered sub-list.
- Unordered
+ Unordered
Чтобы создать ссылку используется синтаксис: [отображаемый текст](ссылка)
:
[I'm a link](https://swiftworld.ru)
Для картинки ситуация аналогичная, разве что добавляется восклицательный знак:

Для подсветки кода можно использовать два стиля - inline, когда код подсвечивается в строке:
`let a = 1`
И многострочный, когда подсвечиваются блоки кода. В таком случае часто указывается название языка, чтобы интерпретатор разметки мог понять, о чём идёт речь:
```swift let a = 1 a += 1 //2 ```
В данном случае подсветки не происходит, так как интерепретатор markdown не знал о swift.
Для использования цитат нужен символ >
:
> Весь мир - всего лишь игра
Горизонтальные линии ставятся с помощью - - - -
:
- - - -
Мы рассмотрели здесь лишь самые основные пункты markdown - ибо к этому стандарту существует множество расширений и некоторые интерпретаторы ведут себя по-своему.