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

Ένα σχόλιο πολλαπλών γραμμών που διαθέτει ένα επιπλέον «*» στην αρχή αποτελεί ένα μπλοκ τεκμηρίωσης που λαμβάνεται υπόψη από τα εργαλεία του 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 για να αναφερθείτε σε ένα πεδίο μέσα σε μια δομή και #GObjectClass.foo_bar() για να αναφερθείτε σε μια vmethod.

Αν θέλετε να χρησιμοποιήσετε τους ειδικούς χαρακτήρες «<», «>», «()», «@», «%» ή «#» στην τεκμηρίωση, χωρίς να φοβάστε ότι θα τους αλλάξει το GTK-Doc, μπορείτε να χρησιμοποιήσετε τις οντότητες XML «&lt;», «&gt;», «&lpar;», «&rpar;», «&commat;», «&percnt;» και «&num;», αντίστοιχα, ή να χρησιμοποιήσετε την ανάποδη κάθετο «\» ως χαρακτήρα διαφυγής.

Το DocBook μπορεί να κάνει παραπάνω από απλούς συνδέσμους. Μπορεί κάποιος να έχει και λίστες, παραδείγματα, κεφαλίδες και εικόνες. Από την έκδοση 1.20 και μετά, ο προτιμώμενος τρόπος είναι με τη χρήση ενός υποσυνόλου της βασικής σύνταξης για μορφοποίηση κειμένου που ονομάζεται Markdown. Σε παλιότερες εκδόσεις GTK-Doc οποιαδήποτε τεκμηρίωση που περιλαμβάνει Markdown θα αποδίδεται ως έχει. Για παράδειγμα, οι καταχωρήσεις της λίστας θα εμφανίζονται σαν γραμμές που αρχίζουν με μια παύλα.

Αν και τώρα προτιμάται η Markdown μπορεί κάποιος να αναμείξει και τις δύο. Ένας περιορισμός εδώ είναι ότι κάποιος μπορεί να χρησιμοποιήσει το docbook xml μέσα στο markdown, αλλά το markdown μέσα στο docbook xml δεν υποστηρίζεται.

Σε παλιότερες εκδόσεις του GTK-Doc, αν χρειάζεστε υποστήριξη για πρόσθετη μορφοποίηση, θα πρέπει να ενεργοποιήσετε τη χρήση των ετικετών docbook XML μέσα στα doc-comments θέτοντας το --xml-mode (ή το --sgml-mode) στη μεταβλητή MKDB_OPTIONS μέσα στο Makefile.am.

Παράδειγμα 3-3Μπλοκ σχολίου GTK-Doc χρησιμοποιώντας Markdown
/**
 * ταυτοποιητής:
 *
 * παράγραφος τεκμηρίωσης ...
 *
 * # Δευτερεύουσα επικεφαλίδα #
 *
 * ## Δεύτερη δευτερεύουσα επικεφαλίδα
 *
 * # Δευτερεύουσα επικεφαλίδα με μια άγκυρα συνδέσμου # {#επικεφαλίδα-δύο}
 *
 * περισσότερη τεκμηρίωση:
 *
 * - στοιχείο 1 καταλόγου
 *
 *   Παράγραφος μέσα σε ένα στοιχείο καταλόγου.
 *
 * - στοιχείο καταλόγου 2
 *
 * 1. αριθμημένο στοιχείο καταλόγου
 *
 * 2. άλλο αριθμημένο στοιχείο καταλόγου
 *
 * Μια άλλη παράγραφος. [Ένας σύνδεσμος στην ιστοσελίδα GNOME](http://www.gnome.org/)
 *
 * ![μια ενσωματωμένη εικόνα ](plot-result.png)
 *
 * [Ένας σύνδεσμος στην από πάνω άγκυρα επικεφαλίδας][επικεφαλίδα-δύο]
 *
 * Ένα παράδειγμα γλώσσας C:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

Μπορείτε να βρείτε περισσότερα παραδείγματα για το ποιες ετικέτες markdown υποστηρίζονται στη διεύθυνση GTK+ Documentation Markdown Syntax Reference.

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