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

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

Markdown

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

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

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

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

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

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

  Returns `:ok`.

  ## Examples

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

  """
  @doc since: "1.3.0"
  def world(name) do
    IO.puts("hello #{name}")
  end
end

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

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

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

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

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

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

Метаданные документации

Elixir позволяет разработчикам добавлять произвольные метаданные к документации. Это делается путём передачи списка ключевых слов соответствующему атрибуту (такому как @moduledoc, @typedoc, и @doc). Часто используемые метаданные — :since, которые указывают, в какой версии был добавлен конкретный модуль, функция, тип или обратный вызов, как показано в примере выше.

Другими часто используемыми метаданными являются :deprecated, которые генерируют предупреждение в документации, объясняющее, что его использование не рекомендуется:

@doc deprecated: "Use Foo.bar/2 instead"

Обратите внимание, что ключ :deprecated не предупреждает при вызове функций разработчиками. Если вы хотите, чтобы код также генерировал предупреждение, вы можете использовать атрибут @deprecated:

@deprecated "Use Foo.bar/2 instead"

Метаданные могут иметь любой ключ. Инструменты документации часто используют метаданные для предоставления читателям большей информации и обогащения пользовательского опыта.

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

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

• Сохраняйте первый абзац документации лаконичным и простым, обычно одной строкой. Такие инструменты, как 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 ##. Заголовки первого уровня предназначены для имён модулей и функций.

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

• Используйте ключ :since в метаданных документации, чтобы указывать, когда к вашему API добавляются новые функции или модули.

Doctests

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

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

Документация != Комментарии к коду

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

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

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

Наконец, будьте осторожны с избыточными комментариями к коду, такими как те, которые описывают то же самое, что и код:

# Total is the sum of the batch and individual entries
total = batch_sum + individual_sum

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

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

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

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

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

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

Code.fetch_docs/1

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