Documentación en

Acerca de Documentación

La documentación de Elixir:

• Un ciudadano de primera clase.
• Se escribe en Markdown.
• Se agrega usando atributos de módulo especiales.
• Por lo general, usa la sintaxis heredoc para strings multilínea.

Atributos de módulo que se usan 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 typespec.
• @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 vs. 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, y demás.

Como la documentación está pensada para describir la API pública de tu código, intentar agregar un atributo @doc a una función privada dará como resultado una advertencia 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

Consumir la documentación

Hay muchas maneras diferentes 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. Cada paquete que se publica en hex.pm tendrá su documentación publicada automáticamente en hexdocs.pm. Ahí podrás encontrar la documentación de todas tus bibliotecas de Elixir favoritas, así como la 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 producirá archivos HTML que puedes explorar 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 computadora.

Si tienes Elixir instalado en tu computadora, 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 presionas la tecla tab después de escribir parte del nombre de un módulo o de una función, puedes aprovechar la opción de autocompletado para descubrir los módulos y las funciones disponibles.

IDE modernos

Muchos IDE modernos que admiten Elixir pueden analizar y mostrar la documentación y los typespecs 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 solo 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 y/o importar. Consulta la documentación oficial sobre cómo ocultar módulos y funciones internos para conocer posibles soluciones a este problema.