Documentação em

Sobre Documentação

A documentação do Elixir:

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

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

• @moduledoc - descreve um módulo e aparece na primeira linha do módulo.
• @doc - descreve uma função e aparece mesmo por cima da definição da função e da respetiva typespec.
• @typedoc- descreve um tipo personalizado e aparece mesmo por cima 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 a documentação e os comentários de código como dois conceitos diferentes.

A documentação é um contrato explícito entre ti e os utilizadores da tua API pública (que também inclui os teus colegas de trabalho e o teu eu do futuro). Esses utilizadores podem ter ou não acesso ao código-fonte, por isso a documentação explica como usar o teu código.

Os comentários de código destinam-se aos programadores que leem o código-fonte. São úteis para deixar notas, explicar detalhes de implementação, assinalar oportunidades de melhoria, entre outras coisas.

Como a documentação serve para descrever a API pública do teu código, tentar adicionar um atributo @doc a uma função privada vai originar um aviso de compilação. Para explicares funções privadas, usa antes 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

Consumir a documentação

Há muitas formas diferentes de aceder à documentação de um projeto Elixir.

hexdocs.pm e ExDoc

O hex.pm é um repositório de pacotes para Elixir e Erlang. Todos os pacotes publicados no hex.pm têm a respetiva documentação publicada automaticamente no hexdocs.pm. Aí, podes encontrar a documentação de todas as tuas bibliotecas Elixir preferidas, bem como a própria documentação oficial do Elixir.

Podes gerar um site de documentação para o teu projeto com um aspeto exatamente igual ao da documentação oficial do Elixir sem teres de publicar um pacote no hex.pm. A ferramenta que faz isso chama-se ExDoc. O ExDoc produz ficheiros HTML que podes consultar a partir do teu sistema de ficheiros local.

Certifica-te de que segues as recomendações oficiais para escrever documentação para obteres os melhores resultados ao usar o ExDoc.

O auxiliar h do IEx

Podes aceder à documentação da biblioteca padrão, bem como a qualquer biblioteca que tenhas instalado e ao teu projeto Elixir, diretamente a partir do teu computador.

Se tens o Elixir instalado no teu computador, podes usá-lo em o modo interativo executando o comando iex (ou iex -S mix se quiseres carregar o código-fonte do teu projeto mix atual).

No iex, podes escrever h, seguido de um espaço e do nome de um módulo ou de uma função, para ler a respetiva 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 premir a tecla de tabulação depois de escreveres parte do nome de um módulo ou de uma função, podes aproveitar a opção de preenchimento automático para descobrir os módulos e as funções disponíveis.

IDEs modernos

Muitos IDEs modernos que suportam Elixir conseguem analisar e apresentar a documentação e as typespecs em pop-ups úteis, por exemplo o Visual Studio Code ou o Intellij com o plug-in do Elixir.

Módulos e funções internos

Se um módulo ou uma função se destina apenas a uso interno, podes marcá-lo com @moduledoc false ou @doc false. Esses módulos e funções não serão incluídos na documentação gerada. Tem em atenção que isso não os torna privados. Continuam a poder ser invocados e/ou importados. Consulta a documentação oficial sobre como ocultar módulos e funções internos para conheceres possíveis soluções para este problema.