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

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 также может использоваться для прикрепления документации к типам, определённым в рамках типов спецификаций.

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

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

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

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

def size(map_with_size)
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 рассматривает документацию и комментарии к коду как разные понятия. Документация предназначена для пользователей вашего Application Programming Interface (API), будь то ваш коллега или будущее вы. Модули и функции всегда должны быть задокументированы, если они являются частью вашего 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.fetch_docs/1

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