[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]
Παρακάτω αναφέρονται μερικές συμβάσεις σχετικά με το
περιεχόμενο και τη μορφοποίηση των αλφαριθμητικών
τεκμηρίωσης.
Η πρώτη γραμμή πρέπει πάντα να είναι μια σύντομη,
συνοπτική παρουσίαση του σκοπού του αντικειμένου. Για λόγους
συντομίας, δεν θα πρέπει να αναφέρεται ρητά το όνομα ή ο
τύπος του αντικειμένου, δεδομένου ότι αυτά είναι διαθέσιμα
με άλλα μέσα ( εκτός αν το όνομα που τυχαίνει να είναι ένα
ρήμα που περιγράφει τη λειτουργία μιας συνάρτησης). Η γραμμή
αυτή θα πρέπει να αρχίζει με ένα κεφαλαίο γράμμα και να
τελειώνει με μια περίοδο .
Αν υπάρχουν περισσότερες γραμμές στη συμβολοσειρά
τεκμηρίωσης, η δεύτερη γραμμή θα πρέπει να είναι κενή,
διαχωρίζοντας οπτικά την περίληψη από το υπόλοιπο της
περιγραφής. Οι ακόλουθες κατευθυντήριες γραμμές θα πρέπει να
είναι μία ή περισσότερες παράγραφοι που περιγράφουν τις
συμβάσεις για το κάλεσμα του αντικειμένου, τις παρενέργειές
της, κλπ.
Η πρώτη μη κενή γραμμή μετά την πρώτη γραμμή του
αλφαριθμητικού καθορίζει το ποσό της εσοχής για το σύνολο
της συμβολοσειράς τεκμηρίωσης. Το κενό που "ισοδύναμεί" με
αυτή την εγκοπή στη συνέχεια απογυμνώνεται από την έναρξη
του συνόλου των γραμμών του string. Οι γραμμές που
βρίσκονται σε μια μεγαλύτερη εσοχή δεν πρέπει να συμβούν ,
αλλά αν συμβούν όλα οδηγούν κενά τους θα πρέπει να
αφαιρεθούν.
Εδώ είναι ένα παράδειγμα ενός multi-line docstring:
>>>
def
my_function
():
...
"""Do nothing, but document it.
...
...
No, really, it doesn't do anything.
...
"""
...
pass
...
>>>
(my_function
.
__doc__)
- A Mini greek notebook for Learning Python Programming
31