Documentação em

Sobre Documentação

Documentação do Elixir:

• Um cidadão de primeira classe.
• Escrita em Markdown.
• Adicionada com o uso de atributos de módulo especiais.
• Normalmente usa a sintaxe heredoc para strings de várias linhas.

Atributos de módulo usados para documentação:

• @moduledoc - descreve um módulo, aparece na primeira linha do módulo.
• @doc - descreve uma função, aparece logo acima da definição da função e do seu typespec.
• @typedoc- descreve um tipo personalizado, aparece logo acima da definição do tipo.

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

Documentação vs. comentários de código

O Elixir trata documentação e comentários de código como dois conceitos diferentes.

A documentação é um contrato explícito entre você e as pessoas que usam sua API pública (o que também inclui seus colegas de trabalho e você mesmo no futuro). Essas pessoas podem ter ou não acesso ao código-fonte, então a documentação explica como usar o seu código.

Os comentários de código são voltados para quem está lendo o código-fonte. Eles são úteis para deixar anotações, explicar detalhes de implementação, marcar oportunidades de melhoria e assim por diante.

Como a documentação serve para descrever a API pública do seu código, tentar adicionar um atributo @doc a uma função privada vai gerar um aviso de compilação. Para explicar funções privadas, use comentários de código.

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

Como consumir a documentação

Existem muitas formas diferentes de acessar a documentação de um projeto Elixir.

hexdocs.pm e ExDoc

hex.pm é um repositório de pacotes para Elixir e Erlang. Todo pacote publicado no hex.pm tem sua documentação publicada automaticamente no hexdocs.pm. Lá, você encontra a documentação de todas as suas bibliotecas Elixir favoritas, além da documentação oficial do Elixir.

Você pode gerar um site de documentação para o seu projeto que se parece exatamente com a documentação oficial do Elixir, sem precisar publicar um pacote no hex.pm. A ferramenta que faz isso se chama ExDoc. O ExDoc gera arquivos HTML que você pode navegar a partir do seu sistema de arquivos local.

Certifique-se de seguir as recomendações oficiais para escrever documentação para garantir os melhores resultados ao usar o ExDoc.

O auxiliar h do IEx

Você pode acessar a documentação da biblioteca padrão, de qualquer biblioteca que você tenha instalado e do seu projeto Elixir, diretamente do seu computador.

Se você tem o Elixir instalado no seu computador, pode usá-lo no modo interativo rodando o comando iex (ou iex -S mix se quiser carregar o código-fonte do seu projeto mix atual).

No iex, você pode digitar h, seguido de um espaço e o nome de um módulo ou de uma função, para ler sua documentação.

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

Ao pressionar a tecla Tab depois de digitar parte do nome de um módulo ou de uma função, você pode usar o autocompletar para descobrir os módulos e as funções disponíveis.

IDEs modernas

Muitas IDEs modernas que dão suporte a Elixir conseguem interpretar e exibir documentação e typespecs em pop-ups úteis, por exemplo o Visual Studio Code ou o Intellij com o plugin do Elixir.

Módulos e funções internos

Se um módulo ou uma função se destina apenas ao uso interno, você pode marcá-lo com @moduledoc false ou @doc false. Esses módulos e funções não serão incluídos na documentação gerada. Repare que isso não os torna privados. Eles ainda podem ser invocados e/ou importados. Consulte a documentação oficial sobre como ocultar módulos e funções internos para conhecer possíveis soluções para esse problema.