Вступ
Документація
Документація в Elixir є повноправною частиною мови.
Для документування коду зазвичай використовують два атрибути модуля: @moduledoc для документування модуля та @doc для документування функції, що йде після атрибута. Атрибут @moduledoc зазвичай стоїть у першому рядку модуля, а атрибут @doc зазвичай стоїть безпосередньо перед визначенням функції або перед специфікацією типів цієї функції, якщо вона є. Документацію зазвичай записують багаторядковим рядком тексту (англ. string) за допомогою синтаксису heredoc.
Документацію в Elixir пишуть мовою Markdown.
defmodule String do
@moduledoc """
Strings in Elixir are UTF-8 encoded binaries.
"""
@doc """
Converts all characters in the given string to uppercase according to `mode`.
## Examples
iex> String.upcase("abcd")
"ABCD"
iex> String.upcase("olá")
"OLÁ"
"""
def upcase(string, mode \\ :default)
end
Специфікації типів
Elixir належить до динамічно типізованих мов, а це означає, що вона не перевіряє типи під час компіляції. Утім, специфікації типів можна використовувати як різновид документації.
Специфікацію типу можна додати до функції за допомогою атрибута модуля @spec безпосередньо перед визначенням функції. Після @spec записують назву функції та список типів усіх її аргументів у дужках, розділених комами. Тип поверненого значення відокремлюють від аргументів функції подвійною двокрапкою ::.
@spec longer_than?(String.t(), non_neg_integer()) :: boolean()
def longer_than?(string, length), do: String.length(string) > length
Типи
Найпоширеніші типи:
- булеві значення (англ. Boolean):
boolean()
- рядки тексту:
String.t()
- числа:
integer(), non_neg_integer(), pos_integer(), float()
- масиви:
list()
- значення будь-якого типу:
any()
Деякі типи можна також параметризувати: наприклад, list(integer) позначає масив цілих чисел.
Як типи можна використовувати й літеральні значення.
Обʼєднання типів можна записати за допомогою вертикальної риски |. Наприклад, integer() | :error означає або ціле число, або літерал атома :error.
Повний список усіх типів можна знайти в розділі «Typespecs» в офіційній документації.
Аргументи у специфікації типу можна також назвати, що допомагає розрізняти кілька аргументів одного типу. Назва аргументу, після якої йде подвійна двокрапка, ставиться перед типом аргументу.
@spec to_hex({hue :: integer, saturation :: integer, lightness :: integer}) :: String.t()
Власні типи
Специфікації типів не обмежуються лише вбудованими типами. Власні типи можна визначати за допомогою атрибута модуля @type. Визначення власного типу починається з назви типу, далі йде подвійна двокрапка, а потім сам тип.
@type color :: {hue :: integer, saturation :: integer, lightness :: integer}
@spec to_hex(color()) :: String.t()
Власний тип можна використовувати в тому самому модулі, де його визначено, або в іншому модулі.
Вказівки
Ми вже деякий час працюємо в міському офісі й розробили набір інструментів, які прискорюють нашу щоденну роботу, наприклад заповнення бланків.
Тепер до нас приєднується новий колега, і ми зрозуміли, що наші інструменти не пояснюють себе самі. У нашому офісі багато дивних звичаїв: наприклад, бланки завжди заповнюють великими літерами й намагаються не залишати поля порожніми.
Ми вирішуємо написати документацію, щоб новому колезі було легше одразу взятися до роботи й почати користуватися нашими інструментами.
1. Задокументуйте призначення інструментів для бланків
Додайте до модуля Form документацію, яка описує його призначення. Вона має мати такий вигляд:
A collection of loosely related functions helpful for filling out various forms at the city office.
2. Задокументуйте заповнення полів порожніми значеннями
Додайте документацію та специфікацію типів до функції Form.blanks/1. Документація має мати такий вигляд:
Generates a string of a given length.
This string can be used to fill out a form field that is supposed to have no value.
Such fields cannot be left empty because a malicious third party could fill them out with false data.
Специфікація типів має пояснювати, що функція приймає один аргумент, невідʼємне ціле число, і повертає рядок тексту (англ. string).
3. Задокументуйте розбиття значень на масиви великих літер
Додайте документацію та специфікацію типів до функції Form.letters/1. Документація має мати такий вигляд:
Splits the string into a list of uppercase letters.
This is needed for form fields that don't offer a single input for the whole string,
but instead require splitting the string into a predefined number of single-letter inputs.
Специфікація типів має пояснювати, що функція приймає один аргумент, рядок тексту, і повертає масив рядків тексту.
4. Задокументуйте перевірку, чи вміщується значення в поле з максимальною довжиною
Додайте документацію та специфікацію типів до функції Form.check_length/2. Документація має мати такий вигляд:
Checks if the value has no more than the maximum allowed number of letters.
This is needed to check that the values of fields do not exceed the maximum allowed length.
It also tells you by how much the value exceeds the maximum.
Специфікація типів має пояснювати, що функція приймає два аргументи, рядок тексту і невідʼємне ціле число, і повертає одне з двох можливих значень. Вона повертає або атом :ok, або кортеж із двох елементів, у якому перший елемент - атом :error, а другий - додатне ціле число.
З якоїсь невідомої нам причини внутрішня система міського офісу використовує два різні способи подання адрес: або як словник, або як кортеж.
Задокументуйте цей факт, визначивши три власні публічні типи:
-
address_map - словник із ключами :street, :postal_code і :city. Кожен ключ містить значення типу рядок тексту.
-
address_tuple - кортеж із трьома значеннями: street, postal_code і city. Кожне значення має тип рядок тексту. Розрізніть ці значення, давши їм назви у специфікації типів.
-
address - може бути або address_map, або address_tuple.
Додайте документацію та специфікацію типів до функції Form.format_address/1. Документація має мати такий вигляд:
Formats the address as an uppercase multiline string.
Специфікація типів має пояснювати, що функція приймає один аргумент, адресу, і повертає рядок тексту.
Навчальна вправа
