Σχόλια τεκμηρίωσης

Ένα σχόλιο πολλαπλών γραμμών που διαθέτει ένα επιπλέον «*» στην αρχή αποτελεί ένα μπλοκ τεκμηρίωσης που λαμβάνεται υπόψη από τα εργαλεία του GTK-Doc.

Παράδειγμα 3-2Μπλοκ σχολίου 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 «&lt;», «&gt;», «&lpar;», «&rpar;», «&commat;», «&percnt;» και «&num;», αντίστοιχα, ή να χρησιμοποιήσετε την ανάποδη κάθετο «\» ως χαρακτήρα διαφυγής.

Το DocBook σας προσφέρει και άλλες δυνατότητες πέρα από τους συνδέσμους. Μπορεί να περιλαμβάνει λίστες, πίνακες και παραδείγματα. Για να επιτρέπεται η χρήση ετικετών SGML/XML στα σχόλια τεκμηρίωσης, θα πρέπει να έχει προστεθεί η επιλογή --xml-mode ή --sgml-mode στη μεταβλητή MKDB_OPTIONS του Makefile.am.

Από το GTK-Doc-1.18 το εργαλείο υποστηρίζει υποσύνολα ή γλώσσα markdown. Κάποιος μπορεί να τα χρησιμοποιήσει για υπό-κεφαλίδες και για απλές κατηγοριοποιημένες λίστες. Στις παλαιότερες εκδόσεις του GTK-Doc το περιεχόμενο θα πρέπει να καταστεί ως έχει (τα στοιχεία της λίστας θα εμφανιστούν σε μία γραμμή χωρισμένες με παύλες).

Παράδειγμα 3-3Μπλοκ σχολίου GTK-Doc χρησιμοποιώντας markdown
/**
 * identifier:
 *
 * documentation ...
 *
 * # Sub heading #
 *
 * more documentation:
 * - list item 1
 * - list item 2
 *
 * Even more docs.
 */

          

Όπως αναφέρθηκε και προηγουμένως το GTK-Doc αναλαμβάνει την τεκμηρίωση του δημόσιου API. Άρα, δεν μπορεί να γραφτεί τεκμηρίωση για στατικά σύμβολα. Παρόλα αυτά, συνιστάται ο σχολιασμός και αυτών των συμβόλων, γιατί βοηθά στην κατανόηση του κώδικα. Σας προτείνουμε λοιπόν να τα σχολιάζετε χρησιμοποιώντας κανονικά σχόλια (χωρίς το δεύτερο «*» στην πρώτη γραμμή). Αν αργότερα χρειαστεί να μετατραπεί η συνάρτηση σε δημόσια, το μόνο που θα πρέπει να γίνει είναι να προστεθεί άλλο ένα «*» στο μπλοκ του σχολίου, και να εισαχθεί το όνομα του συμβόλου στην κατάλληλη θέση του αρχείου ενοτήτων.