Documentación en

Acerca de Documentación

Documentación de Elixir:

• Un ciudadano de primera clase.
• Escrita en Markdown.
• Se añade mediante atributos de módulo especiales.
• Normalmente usa la sintaxis heredoc para strings de varias líneas.

Atributos de módulo usados para la documentación:

• @moduledoc: describe un módulo, aparece en la primera línea del módulo.
• @doc: describe una función, aparece justo encima de la definición de la función y de su especificación de tipos.
• @typedoc: describe un tipo personalizado, aparece justo encima de la definición del 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

Documentación frente a comentarios de código

Elixir trata la documentación y los comentarios de código como dos conceptos diferentes.

La documentación es un contrato explícito entre tú y los usuarios de tu API pública (que también incluye a tus compañeros de trabajo y a tu yo del futuro). Es posible que esos usuarios tengan o no acceso al código fuente, así que la documentación explica cómo usar tu código.

Los comentarios de código están dirigidos a los desarrolladores que leen el código fuente. Son útiles para dejar notas, explicar detalles de implementación, marcar oportunidades de mejora, etcétera.

Como la documentación está pensada para describir la API pública de tu código, intentar añadir un atributo @doc a una función privada provocará un aviso de compilación. Para explicar funciones privadas, usa comentarios de código en su lugar.

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

Cómo consumir la documentación

Hay muchas formas distintas de acceder a la documentación de un proyecto de Elixir.

hexdocs.pm y ExDoc

hex.pm es un repositorio de paquetes para Elixir y Erlang. Todos los paquetes publicados en hex.pm verán su documentación publicada automáticamente en hexdocs.pm. Allí puedes encontrar la documentación de todas tus bibliotecas de Elixir favoritas, así como la propia documentación oficial de Elixir.

Puedes generar un sitio web de documentación para tu proyecto que se vea exactamente igual que la documentación oficial de Elixir sin tener que publicar un paquete en hex.pm. La herramienta que lo hace se llama ExDoc. ExDoc genera archivos HTML que puedes consultar desde tu sistema de archivos local.

Asegúrate de seguir las recomendaciones oficiales para escribir documentación para obtener los mejores resultados al usar ExDoc.

El asistente h de IEx

Puedes acceder a la documentación de la biblioteca estándar, así como de cualquier biblioteca que tengas instalada y de tu proyecto de Elixir, directamente desde tu ordenador.

Si tienes Elixir instalado en tu ordenador, puedes usarlo en el modo interactivo ejecutando el comando iex (o iex -S mix si quieres cargar el código fuente de tu proyecto mix actual).

En iex, puedes escribir h, seguido de un espacio y el nombre de un módulo o de una función, para leer su documentación.

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

Si pulsas la tecla de tabulación después de escribir el nombre parcial de un módulo o de una función, puedes aprovechar la opción de autocompletado para descubrir los módulos y funciones disponibles.

IDE modernos

Muchos IDE modernos compatibles con Elixir pueden analizar y mostrar la documentación y las especificaciones de tipos en ventanas emergentes útiles, por ejemplo Visual Studio Code o Intellij con el plugin de Elixir.

Módulos y funciones internos

Si un módulo o una función está pensado únicamente para uso interno, puedes marcarlo con @moduledoc false o @doc false. Esos módulos y funciones no se incluirán en la documentación generada. Ten en cuenta que eso no los hace privados. Todavía se pueden invocar o importar. Consulta la documentación oficial sobre cómo ocultar módulos y funciones internos para conocer posibles soluciones a este problema.