Εισαγωγή
Τεκμηρίωση
Η τεκμηρίωση στο Elixir είναι πολίτης πρώτης κατηγορίας.
Υπάρχουν δύο χαρακτηριστικά μονάδας που χρησιμοποιούνται συνήθως για να τεκμηριώσεις τον κώδικά σου: το @moduledoc για την τεκμηρίωση μιας μονάδας και το @doc για την τεκμηρίωση μιας συνάρτησης που ακολουθεί το χαρακτηριστικό. Το χαρακτηριστικό @moduledoc εμφανίζεται συνήθως στην πρώτη γραμμή της μονάδας, και το χαρακτηριστικό @doc εμφανίζεται συνήθως αμέσως πριν από τον ορισμό μιας συνάρτησης, ή πριν από την προδιαγραφή τύπων της συνάρτησης, αν έχει. Η τεκμηρίωση γράφεται συνήθως σε μια συμβολοσειρά πολλών γραμμών χρησιμοποιώντας τη σύνταξη heredoc.
Η τεκμηρίωση του Elixir είναι γραμμένη σε Markdown.
defmodule String do
@moduledoc """
Strings in Elixir are UTF-8 encoded binaries.
"""
@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 είναι μια δυναμικά τυποποιημένη γλώσσα, που σημαίνει ότι δεν παρέχει ελέγχους τύπων κατά τη μεταγλώττιση. Ωστόσο, οι προδιαγραφές τύπων μπορούν να χρησιμοποιηθούν ως μια μορφή τεκμηρίωσης.
Μια προδιαγραφή τύπων μπορεί να προστεθεί σε μια συνάρτηση χρησιμοποιώντας το χαρακτηριστικό μονάδας @spec, αμέσως πριν από τον ορισμό της συνάρτησης. Μετά το @spec ακολουθεί το όνομα της συνάρτησης και μια λίστα με τους τύπους όλων των ορισμάτων της, μέσα σε παρενθέσεις, χωρισμένους με κόμματα. Ο τύπος της τιμής επιστροφής χωρίζεται από τα ορίσματα της συνάρτησης με μια διπλή άνω τελεία ::.
@spec longer_than?(String.t(), non_neg_integer()) :: boolean()
def longer_than?(string, length), do: String.length(string) > length
Τύποι
Οι πιο συχνά χρησιμοποιούμενοι τύποι περιλαμβάνουν:
- Boolean:
boolean()
- συμβολοσειρές:
String.t()
- αριθμοί:
integer(), non_neg_integer(), pos_integer(), float()
- λίστες:
list()
- τιμή οποιουδήποτε τύπου:
any()
Κάποιοι τύποι μπορούν επίσης να παραμετροποιηθούν, για παράδειγμα το list(integer) είναι μια λίστα με ακέραιους.
Και οι κυριολεκτικές τιμές μπορούν να χρησιμοποιηθούν ως τύποι.
Μια ένωση τύπων μπορεί να γραφτεί χρησιμοποιώντας την κάθετο |. Για παράδειγμα, το integer() | :error σημαίνει είτε έναν ακέραιο είτε το άτομο :error.
Ένας πλήρης κατάλογος όλων των τύπων βρίσκεται στην ενότητα "Typespecs" της επίσημης τεκμηρίωσης.
Ονομασία ορισμάτων
Τα ορίσματα στην προδιαγραφή τύπων μπορούν επίσης να ονομαστούν, κάτι που είναι χρήσιμο για να ξεχωρίζεις πολλά ορίσματα του ίδιου τύπου. Το όνομα του ορίσματος, ακολουθούμενο από μια διπλή άνω τελεία, μπαίνει πριν από τον τύπο του ορίσματος.
@spec to_hex({hue :: integer, saturation :: integer, lightness :: integer}) :: String.t()
Προσαρμοσμένοι τύποι
Οι προδιαγραφές τύπων δεν περιορίζονται μόνο στους ενσωματωμένους τύπους. Οι προσαρμοσμένοι τύποι μπορούν να οριστούν χρησιμοποιώντας το χαρακτηριστικό μονάδας @type. Ο ορισμός ενός προσαρμοσμένου τύπου ξεκινά με το όνομα του τύπου, ακολουθούμενο από μια διπλή άνω τελεία και μετά τον ίδιο τον τύπο.
@type color :: {hue :: integer, saturation :: integer, lightness :: integer}
@spec to_hex(color()) :: String.t()
Ένας προσαρμοσμένος τύπος μπορεί να χρησιμοποιηθεί από την ίδια μονάδα όπου ορίζεται, ή από μια άλλη μονάδα.
Οδηγίες
Δουλεύεις στο δημοτικό γραφείο εδώ και καιρό και έχεις αναπτύξει ένα σύνολο εργαλείων που επιταχύνουν την καθημερινή σου εργασία, για παράδειγμα με τη συμπλήρωση φορμών.
Τώρα, ένας νέος συνάδελφος έρχεται να δουλέψει μαζί σου και συνειδητοποίησες ότι τα εργαλεία σου μπορεί να μην είναι αυτονόητα. Υπάρχουν πολλές περίεργες συμβάσεις στο γραφείο σου, όπως να συμπληρώνεις πάντα τις φόρμες με κεφαλαία γράμματα και να αποφεύγεις να αφήνεις πεδία κενά.
Αποφασίζεις να γράψεις λίγη τεκμηρίωση ώστε ο νέος συνάδελφός σου να ξεκινήσει αμέσως και να αρχίσει να χρησιμοποιεί τα εργαλεία σου.
Πρόσθεσε τεκμηρίωση στην ενότητα Form που να περιγράφει τον σκοπό της. Θα πρέπει να λέει:
A collection of loosely related functions helpful for filling out various forms at the city office.
2. Τεκμηρίωσε τη συμπλήρωση πεδίων με κενές τιμές
Πρόσθεσε τεκμηρίωση και ένα typespec στη συνάρτηση Form.blanks/1. Η τεκμηρίωση θα πρέπει να λέει:
Generates a string of a given length.
This string can be used to fill out a form field that is supposed to have no value.
Such fields cannot be left empty because a malicious third party could fill them out with false data.
Το typespec θα πρέπει να εξηγεί ότι η συνάρτηση δέχεται ένα μόνο όρισμα, έναν μη αρνητικό ακέραιο, και επιστρέφει μια συμβολοσειρά.
3. Τεκμηρίωσε τον διαχωρισμό τιμών σε λίστες με κεφαλαία γράμματα
Πρόσθεσε τεκμηρίωση και ένα typespec στη συνάρτηση Form.letters/1. Η τεκμηρίωση θα πρέπει να λέει:
Splits the string into a list of uppercase letters.
This is needed for form fields that don't offer a single input for the whole string,
but instead require splitting the string into a predefined number of single-letter inputs.
Το typespec θα πρέπει να εξηγεί ότι η συνάρτηση δέχεται ένα μόνο όρισμα, μια συμβολοσειρά, και επιστρέφει μια λίστα συμβολοσειρών.
4. Τεκμηρίωσε τον έλεγχο αν μια τιμή χωράει σε ένα πεδίο με μέγιστο μήκος
Πρόσθεσε τεκμηρίωση και ένα typespec στη συνάρτηση Form.check_length/2. Η τεκμηρίωση θα πρέπει να λέει:
Checks if the value has no more than the maximum allowed number of letters.
This is needed to check that the values of fields do not exceed the maximum allowed length.
It also tells you by how much the value exceeds the maximum.
Το typespec θα πρέπει να εξηγεί ότι η συνάρτηση δέχεται δύο ορίσματα, μια συμβολοσειρά και έναν μη αρνητικό ακέραιο, και επιστρέφει μία από δύο πιθανές τιμές. Επιστρέφει είτε το άτομο :ok είτε μια 2-πλειάδα με πρώτο στοιχείο το άτομο :error και δεύτερο έναν θετικό ακέραιο.
5. Τεκμηρίωσε τις διαφορετικές μορφές διεύθυνσης
Για κάποιον άγνωστο σε σένα λόγο, το εσωτερικό σύστημα του δημοτικού γραφείου χρησιμοποιεί δύο διαφορετικούς τρόπους αναπαράστασης διευθύνσεων: είτε ως χάρτη είτε ως πλειάδα.
Τεκμηρίωσε αυτό το γεγονός ορίζοντας τρεις προσαρμοσμένους δημόσιους τύπους:
-
address_map - ένας χάρτης με κλειδιά :street, :postal_code και :city. Κάθε κλειδί περιέχει μια τιμή τύπου συμβολοσειράς.
-
address_tuple - μια πλειάδα με τρεις τιμές: street, postal_code και city. Κάθε τιμή είναι τύπου συμβολοσειράς. Διαφοροποίησε τις τιμές δίνοντάς τους ονόματα στο typespec.
-
address - μπορεί να είναι είτε ένα address_map είτε ένα address_tuple.
6. Τεκμηρίωσε τη μορφοποίηση της διεύθυνσης
Πρόσθεσε τεκμηρίωση και ένα typespec στη συνάρτηση Form.format_address/1. Η τεκμηρίωση θα πρέπει να λέει:
Formats the address as an uppercase multiline string.
Το typespec θα πρέπει να εξηγεί ότι η συνάρτηση δέχεται ένα όρισμα, μια διεύθυνση, και επιστρέφει μια συμβολοσειρά.
Άσκηση εκμάθησης
