Fork me on GitHub

Τεκμηρίωση

Τεκμηρίωση κώδικα Elixir.

Πίνακας περιεχομένων

Σχολιασμός

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

Η Elixir χειρίζεται την τεκμηρίωση σαν πελάτη πρώτης κατηγορίας, παρέχοντας διάφορες λειτουργίες για την πρόσβαση και τη δημιουργία τεκμηρίωσης για τα projects μας. O πυρήνας της Elixir μας παρέχει πολλές διαφορετικές ιδιότητες για να σχολιάσουμε μια βάση κώδικα. Ας δούμε 3 τρόπους:

Τεκμηρίωση στην ίδια γραμμή

Πιθανότατα ο πιο απλός τρόπος να σχολιάσουμε τον κώδικά μας με σχόλια στην ίδια γραμμή. Παρόμοια με την Ruby ή την Python, τα σχόλια της Elixir χαρακτηρίζονται με το σύμβολο #, γνωστό και ως δίεση ή σαν pound και hash, ανάλογα με την καταγωγή σας.

Για παράδειγμα το ακόλουθο Script Elixir (greeting.exs):

# Εμφανίζει το 'Γειά σου, φιλαράκι' στην κονσόλα.
IO.puts "Γεια σου, " <> "φιλαράκι."

Η Elixir, όταν τρέξει το script θα αγνοήσει οτιδήποτε μετά το # και μέχρι το τέλος της γραμμής, μεταχειρίζοντας το σαν δεδομένα για πέταμα. Μπορεί να μην προσθέτει αξία στην εκτέλεση ή στην επίδοση του script, αλλά όταν δεν είναι τόσο εμφανές τι συμβαίνει, ένας προγραμματιστής θα πρέπει να ξέρει διαβάζοντας το σχόλιό σας. Προσέξτε μην το παρακάνετε με τα σχόλια ίδιας γραμμής! Το να γεμίζετε με σκουπίδια μια βάση κώδικα μπορεί να γίνει εφιάλτης για κάποιους. Καλύτερα να χρησιμοποιείται με μέτρο.

Τεκμηρίωση Ενοτήτων

Ο σχολιαστής @moduledoc επιτρέπει για τεκμηρίωση σε επίπεδο ενότητας. Συνήθως βρίσκεται ακριβώς από κάτω από τη δήλωση defmodule στην κορυφή του αρχείου. Το παρακάτω παράδειγμα δείχνει ένα σχόλια μιας γραμμής μέσα στο σχολιαστή @moduledoc.

defmodule Greeter do
  @moduledoc """
  Παρέχει μια συνάρτηση `hello/1` για να χαιρετίσουμε έναν άνθρωπο
  """

  def hello(name) do
    "Γειά σου, " <> name
  end
end

Εμείς (ή άλλοι) μπορούμε να έχουμε πρόσβαση στην τεκμηρίωση χρησιμοποιώντας τη βοηθητική συνάρτηση h μέσα στο IEx.

iex> c("greeter.ex")
[Greeter]

iex> h Greeter

                Greeter

Παρέχει μια συνάρτηση hello/1 για να χαιρετίσει έναν άνθρωπο

Τεκμηρίωση συναρτήσεων

Όπως η Elixir μας δίνει τη δυνατότητα για τεκμηρίωση επιπέδου ενότητας, επίσης δίνει παρόμοιους σχολιαστές για τη τεκμηρίωση συναρτήσεων. Ο σχολιαστής @doc μας επιτρέπει την τεκμηρίωση σε επίπεδο συνάρτησης. Ο σχολιαστής @doc βρίσκεται ακριβώς από πάνω από τη συνάρτηση που σχολιάζει.

defmodule Greeter do
  @moduledoc """
  ...
  """

  @doc """
  Prints a hello message
  Τυπώνει ένα μήνυμα χαιρετισμού

  ## Παράμετροι

    - name: Αλφαριθμητικό που αναπαριστά το όνομα του ατόμου.

  ## Παραδείγματα

      iex> Greeter.hello("Sean")
      "Γεια σου, Sean"

      iex> Greeter.hello("pete")
      "Γειά σου, pete"

  """
  @spec hello(String.t) :: String.t
  def hello(name) do
    "Γειά σου, " <> name
  end
end

Αν μπούμε στο IEx ξανά και χρησιμοποιήσουμε την εντολή βοήθειας (h) στη συνάρτηση με το όνομα της ενότητας πιο πριν, θα δούμε το ακόλουθο:

iex> c("greeter.ex")
[Greeter]

iex> h Greeter.hello

                def hello(name)

Τυπώνει ένα μήνυμα χαιρετισμού

Παράμετροι

   name: Αλφαριθμητικό που αναπαριστά το όνομα του ατόμου.

Παραδείγματα

    iex> Greeter.hello("Sean")
    "Γειά σου, Sean"

    iex> Greeter.hello("pete")
    "Γειά σου, pete"

iex>

Παρατηρείτε πως μπορείτε να χρησιμοποιήσετε σημάνσεις μέσα στην τεκμηρίωση και το τερματικό θα τις εμφανίσει; Εκτός από το να είναι πολύ συναρπαστικές και μια καινοτομική προσθήκη στο οικοσύστημα της Elixir, γίνεται πολύ πιο σημαντική όταν ασχοληθούμε με το ExDoc για να παράγουμε τεκμηρίωση σε HTML δυναμικά.

ExDoc

Το ExDoc είναι ένα επίσημο project της Elixir το οποίο μπορείτε να το βρείτε στο GitHub. Παράγει HTML (HyperText Markup Language) και ζωντανή τεκμηρίωση για τα projects της Elixir. Ας φτιάξουμε πρώτα ένα Mix project για την εφαρμογή μας:

$ mix new greet_everyone

* creating README.md
* creating .gitignore
* creating mix.exs
* creating config
* creating config/config.exs
* creating lib
* creating lib/greet_everyone.ex
* creating test
* creating test/test_helper.exs
* creating test/greet_everyone_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd greet_everyone
    mix test

Run "mix help" for more commands.

$ cd greet_everyone

Τώρα αντιγράψτε και επικολλήστε τον κώδικά σας από μάθημα για τον σχολιαστή @doc σε ένα αρχείο που ονομάζεται lib/greeter.ex και βεβαιωθείτε ότι όλα δουλεύουν από τη γραμμή εντολών. Τώρα που δουλεύουμε μέσα σε ένα project Mix πρέπει να ξεκινήσουμε το IEx λίγο διαφορετικά, χρησιμοποιώντας την αλληλουχία εντολών iex -S mix:

iex> h Greeter.hello

                def hello(name)

Τυπώνει ένα μήνυμα χαιρετισμού

Παράμετροι

  • name: Αλφαριθμητικό που αναπαριστά το όνομα ένος ατόμου.

Παραδείγματα

    iex> Greeter.hello("Sean")
    "Γειά σου, Sean"

    iex> Greeter.hello("pete")
    "Γειά σου, pete"

Εγκατάσταση

Λαμβάνοντας υπόψιν μας ότι όλα είναι οκ, και ότι βλέπουμε την έξοδο από πάνω σημαίνει ότι είμαστε έτοιμοι να εγκαταστήσουμε το ExDoc. Μέσα στο αρχείο mix.exs προσθέστε τις δύο απαιτόυμενες εξαρτήσεις για να ξεκινήσετε: :earmark και :ex_doc.

  def deps do
    [{:earmark, "~> 0.1", only: :dev},
    {:ex_doc, "~> 0.11", only: :dev}]
  end

Καθορίζουμε το ζευγάρι κλειδί-τιμή only: :dev καθώς δεν θέλουμε να κατεβάσουμε και να συντάξουμε τις εξαρτήσεις αυτές σε ένα περιβάλλον παραγωγής. Αλλά γιατί το Earmark; Το Earmark είναι ένας αναλυτής Markdown για την Elixir το οποίο χρησιμοποιεί το ExDoc για να μετατρέψει την τεκμηρίωσή μας μέσα στα @moduledoc και @doc για να έχουμε πανέμορφη στην εμφάνιση HTML.

Είναι σημαντικό να σημειώσουμε σε αυτό το σημείο ότι δεν είστε υποχρεωμένοι να χρησιμοποιήσετε το Earmark. Μπορείτε να αλλάξετε το εργαλείο σήμανσης με άλλα όπως το Pandoc, το Hoedown ή το Cmark. Πάντως θα χρειαστείτε να κάνετε λίγες παραπάνω ρυθμίσεις για τις οποίες μπορείτε να διαβάσετε εδώ. Για αυτό το φροντιστήριο θα μείνουμε με το Earmark.

Παραγωγή Τεκμηρίωσης

Συνεχίζοντας, από τη γραμμή εντολών τρέξτε τις ακόλουθες δύο εντολές:

$ mix deps.get # φέρνει τα ExDoc + Earmark.
$ mix docs # φτιάχνει την τεκμηρίωση

Docs successfully generated.
View them at "doc/index.html".

Λογικά, αν όλα πήγαν καλά, θα πρέπει να βλέπετε ένα παρόμοιο μήνυμα με το μήνυμα εξόδου στο από πάνω παράδειγμα. Ας δούμε τώρα μεσα στο Mix project μας και να θα πρέπει να δούμε ότι υπάρχει ένας ακόμα φάκελος που ονομάζεται doc/. Μέσα του βρίσκεται η δημιουργημένη τεκμηρίωσή μας. Αν επισκεφθούμε την σελίδα index στο browser μας θα πρέπει να δούμε τα παρακάτω:

ExDoc Screenshot 1

We can see that Earmark has rendered our markdown and ExDoc is now displaying it in a useful format.

ExDoc Screenshot 2

Μπορούμε να το διαθέσουμε στο GitHub, στο website μας, πιο ειδικά στα HexDocs.

Καλές Πρακτικές

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

defmodule Greeter do
  @moduledoc """
  Αυτή είναι καλή τεκμηρίωση.
  """

end
defmodule Greeter do
  @moduledoc false

end
defmodule Greeter do
  @moduledoc """
  ...

  Αυτή η ενότητα επίσης έχει μια συνάρτηση `hello/1`
  """

  def hello(name) do
    IO.puts "Γειά σου, " <> name
  end
end
defmodule Greeter do
  @moduledoc """
  ...

  Αυτή η ενότητα επίσης έχει μια συνάρτηση `hello/1`
  """

  alias Goodbye.bye_bye
  # και ούτω καθεξής

  def hello(name) do
    IO.puts "Γειά σου, " <> name
  end
end
defmodule Greeter do
  @moduledoc """
  ...
  """

  @doc """
  Τυπώνει ένα μήνυμα χαιρετισμού

  ## Παράμετροι

    - name: Αλφαριθμητικό που αναπαριστά το όνομα ενός ατόμου.

  ## Παραδείγματα

      iex> Greeter.hello("Sean")
      "Γειά σου, Sean"

      iex> Greeter.hello("pete")
      "Γειά σου, pete"

  """
  @spec hello(String.t) :: String.t
  def hello(name) do
    "Γειά σου, " <> name
  end
end

Share This Page