Dokumentation in

Über Dokumentation

Elixir-Dokumentation:

• Ein erstklassiger Bestandteil der Sprache.
• Geschrieben in Markdown.
• Hinzugefügt mithilfe spezieller Modulattribute.
• Verwendet typischerweise die Heredoc-Syntax für mehrzeilige Strings.

Modulattribute für die Dokumentation:

• @moduledoc - beschreibt ein Modul und steht in der ersten Zeile des Moduls.
• @doc - beschreibt eine Funktion und steht direkt über der Definition der Funktion und ihrer Typspezifikation.
• @typedoc- beschreibt einen eigenen Typ und steht direkt über der Definition des Typs.

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

Dokumentation vs. Codekommentare

Elixir behandelt Dokumentation und Codekommentare als zwei verschiedene Konzepte.

Dokumentation ist ein ausdrücklicher Vertrag zwischen dir und den Nutzern deiner öffentlichen API (zu denen auch deine Kollegen und dein zukünftiges Ich gehören). Diese Nutzer haben vielleicht Zugriff auf den Quellcode, vielleicht auch nicht. Deshalb erklärt die Dokumentation, wie man deinen Code verwendet.

Codekommentare richten sich an Entwickler, die den Quellcode lesen. Sie sind nützlich, um Notizen zu hinterlassen, Implementierungsdetails zu erklären, Verbesserungsmöglichkeiten zu markieren und so weiter.

Da die Dokumentation die öffentliche API deines Codes beschreiben soll, führt der Versuch, einer privaten Funktion ein @doc-Attribut hinzuzufügen, zu einer Warnung beim Kompilieren. Um private Funktionen zu erklären, verwende stattdessen Codekommentare.

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

Dokumentation nutzen

Es gibt viele verschiedene Möglichkeiten, auf die Dokumentation eines Elixir-Projekts zuzugreifen.

hexdocs.pm und ExDoc

hex.pm ist ein Paket-Repository für Elixir und Erlang. Für jedes Paket, das auf hex.pm veröffentlicht wird, wird die Dokumentation automatisch auf hexdocs.pm veröffentlicht. Dort findest du die Dokumentation für alle deine Lieblingsbibliotheken von Elixir sowie die offizielle Dokumentation von Elixir selbst.

Du kannst für dein Projekt eine Dokumentations-Website erzeugen, die genau wie die offizielle Dokumentation von Elixir aussieht, ohne ein Paket auf hex.pm veröffentlichen zu müssen. Das Tool, das das erledigt, heißt ExDoc. ExDoc erzeugt HTML-Dateien, die du von deinem lokalen Dateisystem aus durchstöbern kannst.

Befolge unbedingt die offiziellen Empfehlungen zum Schreiben von Dokumentation, damit du mit ExDoc die besten Ergebnisse erzielst.

Der h-Helfer von IEx

Du kannst direkt von deinem Computer aus auf die Dokumentation der Standardbibliothek zugreifen, ebenso auf jede Bibliothek, die du installiert hast, und auf dein Elixir-Projekt.

Wenn du Elixir auf deinem Computer installiert hast, kannst du es im interaktiven Modus verwenden, indem du den Befehl iex ausführst (oder iex -S mix, wenn du den Quellcode deines aktuellen Mix-Projekts laden möchtest).

In iex kannst du h eingeben, gefolgt von einem Leerzeichen und einem Modul- oder Funktionsnamen, um die zugehörige Dokumentation zu lesen.

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

Wenn du nach einem teilweise eingegebenen Modul- oder Funktionsnamen die Tabulatortaste drückst, kannst du die Autovervollständigung nutzen, um verfügbare Module und Funktionen zu entdecken.

Moderne IDEs

Viele moderne IDEs mit Elixir-Unterstützung können Dokumentation und Typspezifikationen analysieren und in nützlichen Pop-ups anzeigen, zum Beispiel Visual Studio Code oder Intellij mit dem Elixir-Plugin.

Interne Module und Funktionen

Wenn ein Modul oder eine Funktion nur für den internen Gebrauch gedacht ist, kannst du es mit @moduledoc false oder @doc false markieren. Diese Module und Funktionen werden nicht in die erzeugte Dokumentation aufgenommen. Beachte, dass sie dadurch nicht privat werden. Sie können weiterhin aufgerufen und/oder importiert werden. In der offiziellen Dokumentation zum Verstecken interner Module und Funktionen erfährst du mehr über mögliche Lösungen für dieses Problem.