Dokumentáció ebben a kurzusban:

A(z) Dokumentáció fogalomról

Az Elixir dokumentációja:

• Első osztályú állampolgár.
• Markdownban íródik.
• Speciális modulattribútumokkal adható hozzá.
• Általában a heredoc szintaxist használja többsoros stringekhez.

A dokumentációhoz használt modulattribútumok:

• @moduledoc - egy modult ír le, a modul első sorában jelenik meg.
• @doc - egy függvényt ír le, közvetlenül a függvény definíciója és típusspecifikációja fölé kerül.
• @typedoc - egy egyedi típust ír le, közvetlenül a típus definíciója fölé kerül.

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

Dokumentáció kontra kódkommentek

Az Elixir a dokumentációt és a kódkommenteket két különböző fogalomként kezeli.

A dokumentáció egy explicit szerződés közted és a nyilvános API használói között (ide tartoznak a kollégáid és a jövőbeli önmagad is). Lehet, hogy ezeknek a felhasználóknak van hozzáférésük a forráskódhoz, lehet, hogy nincs, ezért a dokumentáció elmagyarázza, hogyan kell használni a kódodat.

A kódkommentek azoknak a fejlesztőknek szólnak, akik a forráskódot olvassák. Hasznosak ahhoz, hogy jegyzeteket hagyjunk velük, megmagyarázzuk a megvalósítás részleteit, megjelöljük a fejlesztési lehetőségeket, és így tovább.

Mivel a dokumentáció a kódod nyilvános API-ját hivatott leírni, ha egy privát függvényhez próbálsz @doc attribútumot adni, az fordítási figyelmeztetést eredményez. A privát függvények magyarázatához inkább kódkommenteket használj.

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

A dokumentáció használata

Számos különböző módon férhetsz hozzá egy Elixir-projekt dokumentációjához.

hexdocs.pm és ExDoc

A hex.pm egy csomagtár Elixirhez és Erlanghoz. Minden hex.pm-en közzétett csomag dokumentációja automatikusan megjelenik a hexdocs.pm oldalon. Ott megtalálod az összes kedvenc Elixir-könyvtárad dokumentációját, valamint magát az Elixir hivatalos dokumentációját is.

Anélkül is generálhatsz egy dokumentációs weboldalt a projektedhez, hogy csomagot kellene közzétenned a hex.pm-en, és ez pontosan úgy fog kinézni, mint az Elixir hivatalos dokumentációja. Azt az eszközt, amely ezt elvégzi, ExDoc néven hívják. Az ExDoc olyan HTML-fájlokat hoz létre, amelyeket a helyi fájlrendszeredről böngészhetsz.

Feltétlenül kövesd a dokumentáció írására vonatkozó hivatalos ajánlásokat, hogy a legjobb eredményt érd el az ExDoc használatakor.

A h IEx-segédeszköz

A standard könyvtár, valamint bármely telepített könyvtár és az Elixir-projekted dokumentációját közvetlenül a számítógépedről érheted el.

Ha telepítve van a gépedre az Elixir, interaktív módban is használhatod az iex parancs futtatásával (vagy az iex -S mix parancséval, ha be szeretnéd tölteni az aktuális mix-projekted forrását).

Az iex-ben beírhatod a h parancsot, utána egy szóközt és egy modul- vagy függvénynevet, hogy elolvasd annak dokumentációját.

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

Ha egy részleges modul- vagy függvénynév beírása után lenyomod a Tab billentyűt, az automatikus kiegészítés segítségével felfedezheted az elérhető modulokat és függvényeket.

Modern IDE-k

Sok Elixirt támogató modern IDE képes feldolgozni és hasznos felugró ablakokban megjeleníteni a dokumentációt és a típusspecifikációkat, például a Visual Studio Code vagy az Intellij az Elixir bővítménnyel.

Belső modulok és függvények

Ha egy modul vagy függvény csak belső használatra készült, megjelölheted @moduledoc false vagy @doc false értékkel. Ezek a modulok és függvények nem kerülnek bele a generált dokumentációba. Vedd figyelembe, hogy ez nem teszi őket priváttá. Továbbra is meghívhatók és/vagy importálhatók. Nézd meg a belső modulok és függvények elrejtéséről szóló hivatalos dokumentációt, hogy megismerd a probléma lehetséges megoldásait.