Documentation en

À propos de Documentation

La documentation d'Elixir :

• Un citoyen de première classe.
• Écrite en Markdown.
• Ajoutée à l'aide d'attributs de module spéciaux.
• Utilise généralement la syntaxe heredoc pour les strings multilignes.

Les attributs de module utilisés pour la documentation :

• @moduledoc : décrit un module, apparaît sur la première ligne du module.
• @doc : décrit une fonction, apparaît juste au-dessus de la définition de la fonction et de sa spécification de type.
• @typedoc : décrit un type personnalisé, apparaît juste au-dessus de la définition du type.

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

Documentation ou commentaires de code

Elixir considère la documentation et les commentaires de code comme deux concepts distincts.

La documentation est un contrat explicite entre toi et les utilisateurs de ton API publique (ce qui inclut aussi tes collègues et toi-même plus tard). Ces utilisateurs ont parfois accès au code source, parfois non, c'est pourquoi la documentation explique comment utiliser ton code.

Les commentaires de code, eux, s'adressent aux développeurs qui lisent le code source. Ils sont utiles pour laisser des notes, expliquer des détails d'implémentation, signaler des pistes d'amélioration, et ainsi de suite.

Comme la documentation est censée décrire l'API publique de ton code, essayer d'ajouter un attribut @doc à une fonction privée provoque un avertissement de compilation. Pour expliquer une fonction privée, utilise plutôt des commentaires de code.

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

Consulter la documentation

Il existe de nombreuses façons d'accéder à la documentation d'un projet Elixir.

hexdocs.pm et ExDoc

hex.pm est un dépôt de paquets pour Elixir et Erlang. Chaque paquet publié sur hex.pm voit sa documentation automatiquement publiée sur hexdocs.pm. Tu y trouveras la documentation de toutes tes bibliothèques Elixir préférées, ainsi que la documentation officielle d'Elixir elle-même.

Tu peux générer pour ton projet un site de documentation qui ressemble exactement à la documentation officielle d'Elixir, sans avoir à publier de paquet sur hex.pm. L'outil qui s'en charge s'appelle ExDoc. ExDoc produit des fichiers HTML que tu peux parcourir depuis ton système de fichiers local.

Pense à suivre les recommandations officielles pour écrire de la documentation afin d'obtenir les meilleurs résultats avec ExDoc.

L'assistant h d'IEx

Tu peux accéder directement depuis ton ordinateur à la documentation de la bibliothèque standard, ainsi qu'à celle de n'importe quelle bibliothèque que tu as installée et de ton projet Elixir.

Si Elixir est installé sur ton ordinateur, tu peux l'utiliser en mode interactif en lançant la commande iex (ou iex -S mix si tu veux charger le code source de ton projet mix courant).

Dans iex, tu peux taper h, suivi d'un espace et d'un nom de module ou de fonction, pour lire sa documentation.

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

En appuyant sur la touche tabulation après avoir saisi le début d'un nom de module ou de fonction, tu peux profiter de l'autocomplétion pour découvrir les modules et les fonctions disponibles.

Les IDE modernes

De nombreux IDE modernes compatibles avec Elixir savent analyser et afficher la documentation et les spécifications de type dans des info-bulles pratiques, par exemple Visual Studio Code ou Intellij avec le plugin Elixir.

Les modules et fonctions internes

Si un module ou une fonction est destiné à un usage interne uniquement, tu peux le marquer avec @moduledoc false ou @doc false. Ces modules et fonctions ne seront pas inclus dans la documentation générée. Note que cela ne les rend pas privés pour autant : ils peuvent toujours être appelés ou importés. Consulte la documentation officielle sur la façon de masquer les modules et fonctions internes pour découvrir des solutions possibles à ce problème.