Документація у

Про концепцію Документація

Документація в Elixir:

• Повноправна частина мови.
• Пишеться в Markdown.
• Додається за допомогою спеціальних атрибутів модуля.
• Зазвичай використовує синтаксис heredoc для багаторядкових рядків тексту (англ. string).

Атрибути модуля, які використовуються для документації:

• @moduledoc - описує модуль, стоїть у першому рядку модуля.
• @doc - описує функцію, стоїть безпосередньо над визначенням функції та її специфікацією типів.
• @typedoc - описує власний тип, стоїть безпосередньо над визначенням типу.

defmodule String do
  @moduledoc """
  Strings in Elixir are UTF-8 encoded binaries.
  """

  @typedoc """
  A UTF-8 encoded binary.
  """
  @type t :: binary

  @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 розглядає документацію та коментарі в коді як два різні поняття.

Документація - це явний контракт між нами та користувачами нашого публічного API (до яких належать також наші колеги й ми самі в майбутньому). Ці користувачі можуть мати або не мати доступу до вихідного коду, тому документація пояснює, як використовувати наш код.

Коментарі в коді призначені для розробників, які читають вихідний код. Вони стають у пригоді, щоб залишити нотатки, пояснити деталі реалізації, позначити можливості для покращення тощо.

Оскільки документація покликана описувати публічний API нашого коду, спроба додати атрибут @doc до приватної функції призведе до попередження під час компіляції. Для пояснення приватних функцій натомість використовуймо коментарі в коді.

warning: defp do_check_length/2 is private, @doc attribute is always discarded for private functions/macros/types
  lib/form.ex:33: Form.do_check_length/2

Використання документації

Існує багато різних способів отримати доступ до документації проєкту Elixir.

hexdocs.pm та ExDoc

hex.pm - це репозиторій пакетів для Elixir та Erlang. Документація кожного пакета, опублікованого в hex.pm, автоматично публікується на hexdocs.pm. Там ми знайдемо документацію до всіх улюблених бібліотек Elixir, а також офіційну документацію Elixir.

Ми можемо згенерувати сайт із документацією для свого проєкту, який матиме точно такий самий вигляд, як офіційна документація Elixir, навіть не публікуючи пакет у hex.pm. Інструмент, який це робить, називається ExDoc. ExDoc створить HTML-файли, які можна переглядати з локальної файлової системи.

Обовʼязково дотримуймося офіційних рекомендацій щодо написання документації, щоб отримати найкращий результат під час використання ExDoc.

Довідкова функція h в IEx

Ми можемо отримати доступ до документації стандартної бібліотеки, будь-якої встановленої бібліотеки та свого проєкту Elixir безпосередньо зі свого компʼютера.

Якщо в нас встановлено Elixir, ми можемо скористатися інтерактивним режимом, виконавши команду iex (або iex -S mix, якщо потрібно завантажити код поточного проєкту mix).

У iex можна ввести h, а потім пробіл і назву модуля чи функції, щоб прочитати її документацію.

iex()> h String.upcase/1
# def upcase(string, mode \\ :default)
#
# Converts all characters in the given string to uppercase according to mode.
# (...)

Натиснувши клавішу Tab після часткової назви модуля чи функції, ми можемо скористатися автодоповненням, щоб знайти доступні модулі та функції.

Сучасні IDE

Багато сучасних IDE, які підтримують Elixir, уміють розбирати й показувати документацію та специфікації типів у зручних спливних вікнах, наприклад Visual Studio Code або Intellij з плагіном Elixir.

Внутрішні модулі та функції

Якщо модуль чи функція призначені лише для внутрішнього використання, їх можна позначити як @moduledoc false або @doc false. Такі модулі та функції не потраплять до згенерованої документації. Зауважмо, що це не робить їх приватними. Їх усе одно можна викликати та/або імпортувати. Перегляньмо офіційну документацію про приховування внутрішніх модулів і функцій, щоб дізнатися про можливі рішення цієї проблеми.