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

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

Markdown

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

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

Атрибуты модулей

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

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

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

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

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

Подводя итог, документация — это соглашение с пользователями вашего 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

Если вы не хотите скрывать весь модуль, вы можете скрыть функции по отдельности:

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

Однако имейте в виду, что @moduledoc false или @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 хранит документацию внутри предварительно определенных фрагментов в байт-коде. Документация не загружается в память при загрузке модулей, а может быть прочитана из байт-кода на диске с помощью функции Code.fetch_docs/1. Недостаток заключается в том, что модули, определенные в памяти, например, те, которые определены в IEx, не могут получить доступ к своей документации, поскольку не записывают свой байт-код на диск.