Σχόλια τεκμηρίωσης
Ένα σχόλιο πολλαπλών γραμμών που διαθέτει ένα επιπλέον «*» στην αρχή αποτελεί ένα μπλοκ τεκμηρίωσης που λαμβάνεται υπόψη από τα εργαλεία του GTK-Doc.
/** * identifier: * documentation ... */
Το 'αναγνωριστικό' είναι μία γραμμή που περιέχει το όνομα του στοιχείου στο οποίο αναφέρεται το σχόλιο. Η σύνταξή του εξαρτάται από τον τύπο του στοιχείου. (ΜΕΛΛΟΝΤΙΚΑ: να προστεθεί πίνακας με τα αναγνωριστικά)
Η ομάδα 'τεκμηρίωσης' επίσης διαφέρει ανάλογα με τον τύπο συμβόλου. Για τους τύπους συμβόλων που δέχονται παραμέτρους όπως συναρτήσεις ή μακροεντολές προηγείται η περιγραφή των παραμέτρων και ακολουθεί μια κενή γραμμή (μόνο '*'). Ακολουθεί η λεπτομερής περιγραφή. Όλες οι γραμμές (εκτός από τις λίστες προγράμματος και τις ενότητες CDATA) που περιέχουν μόνο ένα ' *' (διάστημα-αστερίσκο) μετατρέπονται σε αλλαγές παραγράφου. Αν δεν επιθυμείτε αλλαγή παραγράφου, αλλάξτε το σε ' * ' (διάστημα-αστερίσκος-διάστημα-διάστημα). Αυτό είναι χρήσιμο σε προδιαμορφωμένο κείμενο (λίστες κώδικα).
Όταν τεκμηριώνετε κώδικα, περιγράψτε δύο πλευρές:
- Τι είναι: Το όνομα της κλάσης ή της συνάρτησης μπορεί μερικές φορές να είναι παραπλανητικό για ανθρώπους που δεν έχουν τεχνογνωσία στο θέμα.
- Τι κάνει: Αναφέρει τις κοινές χρήσεις και τις βάζει σε σχέση με άλλο API.
Ένα πλεονέκτημα της χρήσης υπερκειμένου αντί για απλό κείμενο είναι η δυνατότητα προσθήκης συνδέσμων στο έγγραφο. Ωστόσο, η χρήση της σωστής σύνταξης για τη δημιουργία συνδέσμων μπορεί να είναι αρκετά κουραστική διαδικασία. Το GTK-Doc σας βοηθάει, παρέχοντάς σας μια σειρά από χρήσιμες συντμήσεις.
- Χρησιμοποιήστε τη γραφή function() για αναφορές σε συναρτήσεις ή μακροεντολές που δέχονται ορίσματα.
- Χρησιμοποιήστε τη γραφή @param για να αναφερθείτε σε παραμέτρους. Επίσης, χρησιμοποιήστε αυτή τη γραφή για να αναφερθείτε σε παραμέτρους άλλων συναρτήσεων, σχετικών με την περιγραφόμενη.
- Χρησιμοποιήστε τη γραφή %constant για να αναφερθείτε σε σταθερές, π.χ. %G_TRAVERSE_LEAFS.
- Χρησιμοποιήστε τη γραφή #symbol για να αναφερθείτε σε άλλους τύπους συμβόλων, π.χ. δομές, αριθμήσεις και μακροεντολές που δε δέχονται ορίσματα.
- Χρησιμοποιήστε τη γραφή #Object::signal για να αναφερθείτε σε ένα σήμα GObject.
- Χρησιμοποιήστε τη γραφή #Object::property για να αναφερθείτε σε μία ιδιότητα GObject.
- Χρησιμοποιήστε τη γραφή #Struct.field για να αναφερθείτε σε ένα πεδίο μιας δομής.
Αν θέλετε να χρησιμοποιήσετε τους ειδικούς χαρακτήρες «<», «>», «()», «@», «%» ή «#» στην τεκμηρίωση, χωρίς να φοβάστε ότι θα τους αλλάξει το GTK-Doc, μπορείτε να χρησιμοποιήσετε τις οντότητες XML «<», «>», «(», «)», «@», «%» και «#», αντίστοιχα, ή να χρησιμοποιήσετε την ανάποδη κάθετο «\» ως χαρακτήρα διαφυγής.
Το DocBook σας προσφέρει και άλλες δυνατότητες πέρα από τους συνδέσμους. Μπορεί να περιλαμβάνει λίστες, πίνακες και παραδείγματα. Για να επιτρέπεται η χρήση ετικετών SGML/XML στα σχόλια τεκμηρίωσης, θα πρέπει να έχει προστεθεί η επιλογή --xml-mode ή --sgml-mode στη μεταβλητή MKDB_OPTIONS του Makefile.am.
Από το GTK-Doc-1.18 το εργαλείο υποστηρίζει υποσύνολα ή γλώσσα markdown. Κάποιος μπορεί να τα χρησιμοποιήσει για υπό-κεφαλίδες και για απλές κατηγοριοποιημένες λίστες. Στις παλαιότερες εκδόσεις του GTK-Doc το περιεχόμενο θα πρέπει να καταστεί ως έχει (τα στοιχεία της λίστας θα εμφανιστούν σε μία γραμμή χωρισμένες με παύλες).
/** * identifier: * * documentation ... * * # Sub heading # * * more documentation: * - list item 1 * - list item 2 * * Even more docs. */
Όπως αναφέρθηκε και προηγουμένως το GTK-Doc αναλαμβάνει την τεκμηρίωση του δημόσιου API. Άρα, δεν μπορεί να γραφτεί τεκμηρίωση για στατικά σύμβολα. Παρόλα αυτά, συνιστάται ο σχολιασμός και αυτών των συμβόλων, γιατί βοηθά στην κατανόηση του κώδικα. Σας προτείνουμε λοιπόν να τα σχολιάζετε χρησιμοποιώντας κανονικά σχόλια (χωρίς το δεύτερο «*» στην πρώτη γραμμή). Αν αργότερα χρειαστεί να μετατραπεί η συνάρτηση σε δημόσια, το μόνο που θα πρέπει να γίνει είναι να προστεθεί άλλο ένα «*» στο μπλοκ του σχολίου, και να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων.