Написание документации

Elixir рассматривает документацию как элемент первого класса. Это означает, что документация должна быть лёгкой в написании и удобной в чтении. В этом документе вы узнаете, как писать документацию на Elixir, охватывая такие конструкции, как атрибуты модуля, стилистические рекомендации и doctests.

Markdown

Документация Elixir написана с использованием Markdown. В интернете есть множество руководств по Markdown, мы рекомендуем руководства GitHub в качестве точки входа:

• Основные синтаксис написания и форматирования
• Мастерство Markdown

Атрибуты модуля

Документация на Elixir обычно прикрепляется к атрибутам модуля. Давайте рассмотрим пример:

defmodule MyApp.Hello do
  @moduledoc """
  This is the Hello module.
  """

  @doc """
  Says hello to the given `name`.

  Returns `:ok`.

  ## Examples

      iex> MyApp.Hello.world(:john)
      :ok

  """
  def world(name) do
    IO.puts "hello #{name}"
  end
end

Атрибут @moduledoc используется для добавления документации к модулю. Атрибут @doc используется перед функцией для предоставления документации к ней. Помимо вышеперечисленных атрибутов, @typedoc также может использоваться для прикрепления документации к типам, определённым в рамках типовpec.

Аргументы функций

При документировании функции имена аргументов определяются компилятором. Например:

def size(%{size: size}) do
  size
end

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

def size(map)
def size(%{size: size}) do
  size
end

Рекомендации

При написании документации:

• Первый абзац документации должен быть кратким и простым, обычно одной строкой. Инструменты, такие как ExDoc, используют первую строку для генерации сводки.

• Ссылайтесь на модули по их полному имени.

  Markdown использует обратные кавычки (`) для цитирования кода. Elixir надстраивается над этим, чтобы автоматически генерировать ссылки при упоминании имён модулей или функций. По этой причине всегда используйте полные имена модулей. Если у вас есть модуль под названием MyApp.Hello, всегда ссылайтесь на него как на `MyApp.Hello` и никогда как на `Hello`.

• Ссылки на функции указывайте по имени и арности, если они локальные, как в `world/1`, или по модулю, имени и арности, если вы ссылаетесь на внешний модуль: `MyApp.Hello.world/1`.

• Ссылки на @callback начинайте с c:, как в `c:world/1`.

• Ссылки на @type начинайте с t:, как в `t:values/0`.

• Начинайте новые разделы с заголовками второго уровня Markdown ##. Заголовки первого уровня зарезервированы для имён модулей и функций.

• Размещайте документацию перед первым определением многоточечных функций. Документация всегда относится к функции и её арности, а не к каждой строке.

Doctests

Мы рекомендуем разработчикам включать примеры в документацию, часто под своим собственным заголовком ## Examples. Чтобы убедиться, что примеры не устаревают, фреймворк тестов Elixir (ExUnit) предоставляет функцию под названием doctests, которая позволяет разработчикам тестировать примеры в своей документации. Doctests работают, парся фрагменты кода, начинающиеся с iex> из документации. Подробнее можно узнать по ссылке ExUnit.DocTest.

Обратите внимание на ограничения doctests. Когда невозможно использовать doctest для функции, потому что она зависит от состояния или побочных эффектов, мы рекомендуем разработчикам включать примеры непосредственно без подсказки iex>.

Документация ≠ Комментарии

Elixir рассматривает документацию и комментарии к коду как разные понятия. Документация предназначена для пользователей вашего API (Application Programming Interface), будь то ваш коллега или вы сами в будущем. Модули и функции должны быть документированы, если они являются частью вашего API.

Комментарии к коду предназначены для разработчиков, читающих код. Они полезны для маркировки улучшений, записи заметок для разработчиков, читающих код (например, вы решили не вызывать функцию из-за ошибки в библиотеке), и так далее.

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

Скрытие внутренних модулей и функций

Помимо модулей и функций, предоставляемых библиотеками как часть их публичного интерфейса, библиотеки могут также реализовывать важную функциональность, которая не является частью их API. Хотя к этим модулям и функциям можно получить доступ, они предназначены для внутреннего использования в библиотеке и, следовательно, не должны иметь документации для конечных пользователей.

К счастью, Elixir позволяет разработчикам скрывать модули и функции из документации. Например, распространённой практикой документирования внутреннего поведения является установка атрибута @moduledoc в значение false при документировании каждой функции:

defmodule MyApp.Hidden do
  @moduledoc false

  @doc """
  This function won't be listed in docs.
  """
  def function_that_wont_be_listed_in_docs do
    # ...
  end
end

Аналогично, разработчики могут добавить @doc false к функциям, которые они не хотят делать общедоступными:

defmodule MyApp.Sample do
  @doc false
  def add(a, b), do: a + b
end

Однако, помните, что добавление @doc false не делает функцию закрытой. Функцию выше можно всё ещё вызвать как MyApp.Sample.add(1, 2). Более того, если MyApp.Sample импортирован, функция add/2 также будет импортирована в вызывающий модуль. По этим причинам будьте осторожны, добавляя @doc false к функциям, используйте один из двух вариантов:

• Переместите недокументированную функцию в модуль с @moduledoc false, например, MyApp.Hidden, гарантируя, что функция не будет случайно экспонирована или импортирована. Помните, что вы можете использовать @moduledoc false для скрытия всего модуля и всё ещё документировать каждую функцию с помощью @doc. Инструменты всё равно проигнорируют модуль.

• Начните имя функции с одного или двух нижних подчеркиваний, например, __add__/2, и добавьте @doc false. Компилятор не импортирует функции с ведущими нижними подчеркиваниями, и это подсказывает любому, читающему код, о его предполагаемом внутреннем использовании.

Документирование закрытых функций

Elixir предупреждает, если закрытая функция имеет атрибут @doc и игнорирует его содержимое, потому что @doc предназначен только для вашего публичного интерфейса.

Закрытые функции, тем не менее, могут нуждаться во внутренней документации для разработчиков, которые их поддерживают. Это можно сделать с помощью комментариев к коду.

Code.get_docs/2

Elixir хранит документацию внутри предварительно определённых блоков в байткоде. К ней можно получить доступ из Elixir, используя функцию Code.get_docs/2. Это также означает, что к документации обращаются только по необходимости, а не при загрузке модулей виртуальной машиной. Единственный недостаток заключается в том, что модули, определённые в памяти, например, те, что определены в IEx, не могут иметь доступ к своей документации, так как их байткод не записан на диск.