Documentazione in

Informazioni su Documentazione

La documentazione di Elixir:

• È un cittadino di prima classe.
• è scritta in Markdown.
• Si aggiunge usando appositi attributi di modulo.
• Di solito usa la sintassi heredoc per le stringhe multilinea.

Attributi di modulo usati per la documentazione:

• @moduledoc: descrive un modulo, appare sulla prima riga del modulo.
• @doc: descrive una funzione, appare subito sopra la definizione della funzione e la sua typespec.
• @typedoc: descrive un tipo personalizzato, appare subito sopra la definizione 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

Documentazione e commenti nel codice

Elixir tratta la documentazione e i commenti nel codice come due concetti diversi.

La documentazione è un contratto esplicito tra te e chi usa la tua API pubblica, che comprende anche i tuoi colleghi e te stesso in futuro. Queste persone potrebbero avere o non avere accesso al codice sorgente, quindi la documentazione spiega come usare il tuo codice.

I commenti nel codice sono invece rivolti agli sviluppatori che leggono il codice sorgente. Sono utili per lasciare annotazioni, spiegare i dettagli di implementazione, segnalare possibili miglioramenti e così via.

Dato che la documentazione serve a descrivere l'API pubblica del tuo codice, provare ad aggiungere un attributo @doc a una funzione privata produce un avviso di compilazione. Per spiegare le funzioni private, usa invece i commenti nel codice.

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

Come consultare la documentazione

Ci sono molti modi diversi per accedere alla documentazione di un progetto Elixir.

hexdocs.pm ed ExDoc

hex.pm è un repository di pacchetti per Elixir ed Erlang. Ogni pacchetto pubblicato su hex.pm avrà la sua documentazione pubblicata automaticamente su hexdocs.pm. Lì puoi trovare la documentazione di tutte le tue librerie Elixir preferite, oltre che la stessa documentazione ufficiale di Elixir.

Puoi generare un sito web di documentazione per il tuo progetto identico alla documentazione ufficiale di Elixir, senza dover pubblicare un pacchetto su hex.pm. Lo strumento che lo fa si chiama ExDoc. ExDoc produrrà file HTML che puoi consultare dal tuo file system locale.

Assicurati di seguire le raccomandazioni ufficiali per scrivere la documentazione per ottenere i migliori risultati quando usi ExDoc.

La funzione ausiliaria h di IEx

Puoi accedere alla documentazione della libreria standard, così come a quella di qualsiasi libreria che hai installato, e al tuo progetto Elixir, direttamente dal tuo computer.

Se hai Elixir installato sul tuo computer, puoi usarlo in modalità interattiva eseguendo il comando iex (oppure iex -S mix se vuoi caricare il sorgente del tuo progetto mix attuale).

In iex, puoi digitare h, seguito da uno spazio e dal nome di un modulo o di una funzione, per leggerne la documentazione.

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

Premendo il tasto tab dopo aver inserito parte del nome di un modulo o di una funzione, puoi sfruttare il completamento automatico per scoprire i moduli e le funzioni disponibili.

IDE moderni

Molti IDE moderni che supportano Elixir possono analizzare e mostrare documentazione e typespec in comodi pop-up, per esempio Visual Studio Code o Intellij con il plugin per Elixir.

Moduli e funzioni interni

Se un modulo o una funzione è pensato solo per un uso interno, puoi contrassegnarlo con @moduledoc false o @doc false. Questi moduli e funzioni non verranno inclusi nella documentazione generata. Tieni presente che questo non li rende privati. Possono comunque essere chiamati e/o importati. Consulta la documentazione ufficiale su come nascondere moduli e funzioni interni per conoscere le possibili soluzioni a questo problema.