Τεκμηρίωση σε

Σχετικά με την έννοια Τεκμηρίωση

Η τεκμηρίωση στην Elixir:

• Είναι πολίτης πρώτης κατηγορίας.
• Είναι γραμμένη σε Markdown.
• Προστίθεται με ειδικά χαρακτηριστικά μονάδας.
• Συνήθως χρησιμοποιεί τη σύνταξη heredoc για συμβολοσειρές πολλών γραμμών.

Τα χαρακτηριστικά μονάδας που χρησιμοποιούνται για τεκμηρίωση:

• @moduledoc - περιγράφει μια μονάδα, εμφανίζεται στην πρώτη γραμμή της μονάδας.
• @doc - περιγράφει μια συνάρτηση, εμφανίζεται ακριβώς πάνω από τον ορισμό της συνάρτησης και το typespec της.
• @typedoc- περιγράφει έναν προσαρμοσμένο τύπο, εμφανίζεται ακριβώς πάνω από τον ορισμό του τύπου.

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

Τεκμηρίωση έναντι σχολίων κώδικα

Η Elixir αντιμετωπίζει την τεκμηρίωση και τα σχόλια κώδικα ως δύο διαφορετικές έννοιες.

Η τεκμηρίωση είναι ένα ρητό συμβόλαιο ανάμεσα σε εσένα και τους χρήστες του δημόσιου API σου (που περιλαμβάνει επίσης τους συναδέλφους σου και τον μελλοντικό σου εαυτό). Αυτοί οι χρήστες μπορεί να έχουν ή να μην έχουν πρόσβαση στον πηγαίο κώδικα, οπότε η τεκμηρίωση εξηγεί πώς να χρησιμοποιήσεις τον κώδικά σου.

Τα σχόλια κώδικα απευθύνονται σε προγραμματιστές που διαβάζουν τον πηγαίο κώδικα. Είναι χρήσιμα για να αφήνεις σημειώσεις, να εξηγείς λεπτομέρειες υλοποίησης, να σημειώνεις ευκαιρίες για βελτίωση και ούτω καθεξής.

Επειδή η τεκμηρίωση προορίζεται να περιγράφει το δημόσιο API του κώδικά σου, αν προσπαθήσεις να προσθέσεις ένα χαρακτηριστικό @doc σε μια ιδιωτική συνάρτηση, θα πάρεις μια προειδοποίηση μεταγλώττισης. Για να εξηγήσεις ιδιωτικές συναρτήσεις, χρησιμοποίησε σχόλια κώδικα.

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

Χρήση της τεκμηρίωσης

Υπάρχουν πολλοί διαφορετικοί τρόποι να αποκτήσεις πρόσβαση στην τεκμηρίωση ενός έργου Elixir.

hexdocs.pm και ExDoc

Το hex.pm είναι ένα αποθετήριο πακέτων για την Elixir και την Erlang. Η τεκμηρίωση κάθε πακέτου που δημοσιεύεται στο hex.pm δημοσιεύεται αυτόματα στο hexdocs.pm. Εκεί μπορείς να βρεις την τεκμηρίωση για όλες τις αγαπημένες σου βιβλιοθήκες Elixir, καθώς και την επίσημη τεκμηρίωση της Elixir.

Μπορείς να δημιουργήσεις έναν ιστότοπο τεκμηρίωσης για το έργο σου που να μοιάζει ακριβώς με την επίσημη τεκμηρίωση της Elixir, χωρίς να χρειάζεται να δημοσιεύσεις κάποιο πακέτο στο hex.pm. Το εργαλείο που το κάνει αυτό ονομάζεται ExDoc. Το ExDoc θα παράγει αρχεία HTML που μπορείς να περιηγηθείς τοπικά από το σύστημα αρχείων σου.

Φρόντισε να ακολουθήσεις τις επίσημες συστάσεις για τη συγγραφή τεκμηρίωσης για να έχεις τα καλύτερα αποτελέσματα όταν χρησιμοποιείς το ExDoc.

Ο βοηθός h του IEx

Μπορείς να έχεις πρόσβαση στην τεκμηρίωση της βασικής βιβλιοθήκης, καθώς και οποιασδήποτε βιβλιοθήκης έχεις εγκαταστήσει και του έργου σου σε Elixir, απευθείας από τον υπολογιστή σου.

Αν έχεις εγκατεστημένη την Elixir στον υπολογιστή σου, μπορείς να τη χρησιμοποιήσεις σε διαδραστική λειτουργία τρέχοντας την εντολή iex (ή iex -S mix αν θέλεις να φορτώσεις τον πηγαίο κώδικα του τρέχοντος έργου σου σε mix).

Στο iex, μπορείς να πληκτρολογήσεις h, ακολουθούμενο από ένα κενό και το όνομα μιας μονάδας ή μιας συνάρτησης, για να διαβάσεις την τεκμηρίωσή τους.

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

Πατώντας το πλήκτρο Tab αφού πληκτρολογήσεις ένα μέρος του ονόματος μιας μονάδας ή μιας συνάρτησης, μπορείς να αξιοποιήσεις την αυτόματη συμπλήρωση για να ανακαλύψεις τις διαθέσιμες μονάδες και συναρτήσεις.

Σύγχρονα IDE

Πολλά σύγχρονα IDE που υποστηρίζουν την Elixir μπορούν να αναλύουν και να εμφανίζουν την τεκμηρίωση και τα typespecs σε χρήσιμα αναδυόμενα παράθυρα, για παράδειγμα το Visual Studio Code ή το Intellij με το plugin Elixir.

Εσωτερικές μονάδες και συναρτήσεις

Αν μια μονάδα ή μια συνάρτηση προορίζεται μόνο για εσωτερική χρήση, μπορείς να τη σημάνεις με @moduledoc false ή @doc false. Αυτές οι μονάδες και συναρτήσεις δεν θα συμπεριληφθούν στην τεκμηρίωση που παράγεται. Σημείωσε ότι αυτό δεν τις κάνει ιδιωτικές. Μπορούν ακόμα να κληθούν ή/και να εισαχθούν. Δες την επίσημη τεκμηρίωση σχετικά με την απόκρυψη εσωτερικών μονάδων και συναρτήσεων για να μάθεις για πιθανές λύσεις σε αυτό το πρόβλημα.