Τεκμηρίωση ενοτήτων
Κάθε ενότητα της τεκμηρίωσης περιέχει πληροφορίες για μία κλάση ή ένα άρθρωμα. Για να εισάγετε το συστατικό μπορείτε να γράψετε ένα μπλοκ σχολίου ενότητας. Η σύντομη αυτή περιγραφή χρησιμοποιείται και για τον πίνακα περιεχομένων. Όλα τα πεδία @fields είναι προαιρετικά.
/** * SECTION:meepapp * @short_description: the application class * @title: Meep application * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * The application class handles ... */
- SECTION:<name>
-
Το name συνδέει την τεκμηρίωση της ενότητας με το αντίστοιχο μέρος στο αρχείο <package>-sections.txt. Το όνομα που δίνεται εδώ πρέπει να ταιριάζει με την ετικέτα <FILE> στο αρχείο <package>-sections.txt.
- @short_description
-
Περιγραφή της ενότητας σε μία γραμμή, η οποία θα εμφανίζεται, στη συνέχεια, μετά από τους συνδέσμους του πίνακα περιεχομένων και στην αρχή της σελίδας της ενότητας.
- @title
-
Ο τίτλος της ενότητας από προεπιλογή έχει όνομα <name> από τη δήλωση SECTION. Μπορεί να παρακαμφθεί με το πεδίο @title.
- @section_id
-
Παρακάμπτει τη χρήση του τίτλου ως αναγνωριστικό της ενότητας. Για αντικείμενα GOBject το <title> χρησιμοποιείται ως section_id και για άλλες ενότητες είναι <MODULE>-<title>.
- @see_also
-
Λίστα συμβόλων σχετικών με αυτή την ενότητα.
- @stability
-
Άτυπη περιγραφή του επιπέδου σταθερότητας του συγκεκριμένου API. Σας συνιστούμε τη χρήση ενός από τους ακόλουθους όρους:
- Σταθερή - Μια σταθερή διεπαφή επιτρέπει σε τρίτους να αναπτύσσουν εφαρμογές για τις διεπαφές αυτές, να τις δημοσιεύουν και να είναι βέβαιοι ότι οι εφαρμογές θα τρέχουν σε όλες τις ελάσσονες εκδόσεις του προϊόντος (οι οποίες θα είναι μεταγενέστερες της διεπαφής και θα ανήκουν στην ίδια μείζονα έκδοση). Ακόμη και όταν πρόκειται για μείζονες νέες εκδόσεις, οι ασυμβατότητες αναμένεται να είναι σπάνιες και να οφείλονται σε σοβαρούς λόγους.
- Ασταθής - Ασταθείς είναι οι πειραματικές ή μεταβατικές διεπαφές. Συνήθως χρησιμοποιούνται για να παρέχουν σε τρίτους πρώιμη πρόσβαση σε νέες ή διαρκώς εξελισσόμενες τεχνολογίες, ή ως ενδιάμεσες λύσεις για προβλήματα για τα οποία αναμένεται μια γενικότερη λύση. Δεν υφίσταται καμία εγγύηση συμβατότητας μεταξύ μιας ελάσσονας έκδοσης και της επόμενης.
- Ιδιωτική - Διεπαφή που μπορεί να χρησιμοποιηθεί εντός της στοίβας του GNOME, αλλά δε διαθέτει τεκμηρίωση που να απευθύνεται στους τελικούς χρήστες. Τέτοιου είδους συναρτήσεις μπορούν να χρησιμοποιούνται μόνο στο πλαίσιο σαφώς καθορισμένων και τεκμηριωμένων διαδικασιών.
- Εσωτερική - Μια διεπαφή που είναι εσωτερική σε ένα module δεν απαιτεί την ύπαρξη τεκμηρίωσης για τον τελικό χρήστη. Οι συναρτήσεις που δεν περιέχουν τεκμηρίωση θεωρείται ότι είναι εσωτερικές.
- @include
-
Αρχεία #include που εμφανίζονται στη συνοπτική παρουσίαση των ενοτήτων (λίστα αρχείων που χωρίζονται με κόμματα), αντικαθιστώντας την καθολική τιμή στο αρχείο ενότητας ή στη γραμμή εντολών. Πρόκειται για προαιρετικό στοιχείο.
- @image
-
Η εικόνα που θα εμφανίζεται στο πάνω μέρος της σελίδας αναφοράς για αυτή την ενότητα. Αυτή συχνά θα είναι κάποιου είδους διάγραμμα για την απεικόνιση μια κλάσης ή ενός διαγράμματος της σχέσης της με άλλες κλάσεις. Αυτή η καταχώρηση είναι προαιρετική.
Για να μη χρειαστεί να κάνετε εκ νέου μεταγλώττιση μετά από αλλαγές στην τεκμηρίωση, σας προτείνουμε να ενσωματώνετε την τεκμηρίωση των ενοτήτων στο αρχείο του πηγαίου κώδικα, όπου αυτό είναι δυνατό.