Τεκμηρίωση συμβόλων
Κάθε σύμβολο (συνάρτηση, μακροεντολή, δομή, αρίθμηση, σήμα, ιδιότητα) τεκμηριώνεται σε ξεχωριστή ομάδα. Η καταλληλότερη θέση για τις ομάδες είναι δίπλα στους ορισμούς των συμβόλων, γιατί διευκολύνει το έργο συγχρονισμού. Επομένως, η τεκμηρίωση των συναρτήσεων συνήθως βρίσκεται στο αρχείο του πηγαίου κώδικα, ενώ των μακροεντολών, δομών και αριθμήσεων στο αρχείο κεφαλίδας.
- 3.3.1. Γενικές ετικέτες
- 3.3.2. Σχόλια
- 3.3.3. Ομάδα σχολίων συνάρτησης
- 3.3.4. Ομάδα σχολίων ιδιότητας
- 3.3.5. Ομάδα σχολίων σήματος
- 3.3.6. Ομάδα σχολίων δομής
- 3.3.7. Ομάδα σχολίων Enum
3.3.1. Γενικές ετικέτες
Μπορείτε να προσθέσετε πληροφορίες εκδόσεων σε όλα τα στοιχεία της τεκμηρίωσης για να πείτε πότε εισήχθηκε ένα API, ή πότε καταργήθηκε.
- Από:
-
Περιγραφή οπό ποια έκδοση του κώδικα και μετά είναι διαθέσιμο το API.
- Παρωχημένη:
-
Παράγραφος που επισημαίνει ότι θα πρέπει να σταματήσει η χρήση της συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API.
Μπορείτε επίσης να προσθέσετε πληροφορίες σταθερότητας σε όλα τα στοιχεία της τεκμηρίωσης για να δείξετε αν η σταθερότητα API είναι εγγυημένη για αυτά για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου.
Το επίπεδο προεπιλεγμένης σταθερότητας για όλα τα στοιχεία τεκμηρίωσης μπορούν να οριστούν μεταφέροντας το όρισμα --default-stability στην gtkdoc-mkdb με μια άπω τις παρακάτω τιμές.
- Σταθερότητα: σταθερό
-
Σημείωση του στοιχείου ως σταθερού. Αυτό είναι για δημόσια APIs που είναι βέβαια ότι παραμένουν σταθερά για όλες τις μελλοντικές δευτερεύουσες εκδόσεις του έργου.
- Σταθερότητα: ασταθές
-
Σημείωση του στοιχείου ως ασταθούς. Αυτό είναι για τα δημόσια APIs που εκδίδονται ως μια προεπισκόπηση πριν να σταθεροποιηθούν.
- Σταθερότητα: προσωπική
-
Σημείωση του στοιχείου ως προσωπικό. Αυτό είναι για διεπαφές που μπορούν να χρησιμοποιηθούν με σφικτά συνδυασμένες ενότητες, αλλά όχι από ελεύθερα τρίτα μέρη.
/** * foo_get_bar: * @foo: some foo * * Retrieves @foo's bar. * * Returns: @foo's bar * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() instead. */ Bar * foo_get_bar(Foo *foo) { ...
3.3.2. Σχόλια
Οι ομάδες τεκμηρίωσης μπορούν να περιέχουν ετικέτες σχολιασμού. Αυτές οι ετικέτες θα αποδοθούν με συμβουλές οθόνης που περιγράφουν το νόημά τους. Οι ετικέτες χρησιμοποιούνται από το gobject-introspection για τη δημιουργία των συνδέσεων γλώσσας. Ένας λεπτομερής κατάλογος των υποστηριζόμενων ετικετών μπορεί να βρεθεί στο η βίκι.
/** * foo_get_bar: (σχόλιο) * @foo: (σχόλιο): some foo * * Ανακτά @foo's bar. * * Επιστρέφει: (σχόλιο): @foo's bar */ ... /** * foo_set_bar_using_the_frobnicator: (σχόλιο) (ένα άλλο σχόλιο) * (και ένα άλλο σχόλιο) * @foo: (σχόλιο) (ένα άλλο σχόλιο): some foo * * Ορίζει γραμμή στο @foo. */
3.3.3. Ομάδα σχολίων συνάρτησης
Παρακαλούμε να θυμηθείτε να:
- Τεκμηριώστε κατά πόσο τα επιστρεφόμενα αντικείμενα, λίστες, συμβολοσειρές, κ.λπ, θα πρέπει να ελευθερώνονται, να μην ελευθερώνονται ή να απορρίπτονται.
- Τεκμηριώσετε κατά πόσο οι παράμετροι μπορούν να είναι μηδενικές (NULL) και τι συμβαίνει αν είναι.
- Αναφέρετε ενδιαφέρουσες προ-καταστάσεις και μετα-καταστάσεις όπου χρειάζεται.
Το Gtk-doc θεωρεί ότι όλα τα σύμβολα (μακροεντολές, συναρτήσεις, κτλ.) που ξεκινούν με '_' είναι ιδιωτικά και τα μεταχειρίζεται σαν στατικές συναρτήσεις.
/** * function_name: * @par1: description of parameter 1. These can extend over more than * one line. * @par2: description of parameter 2 * @...: a %NULL-terminated list of bars * * The function description goes here. You can use @par1 to refer to parameters * so that they are highlighted in the output. You can also use %constant * for constants, function_name2() for functions and #GtkWidget for links to * other declarations (which may be documented elsewhere). * * Returns: an integer. * * Since: 2.2 * Deprecated: 2.18: Use other_function() instead. */
- Επιστροφές:
-
Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα.
- @...:
-
Σε περίπτωση που η συνάρτηση μπορεί να δεχθεί μεταβλητό αριθμό ορισμάτων (variadic), πρέπει να χρησιμοποιήσετε αυτή την ετικέτα (η ετικέτα @Varargs: λειτουργεί επίσης, για ιστορικούς λόγους).
3.3.4. Ομάδα σχολίων ιδιότητας
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.5. Ομάδα σχολίων σήματος
Παρακαλούμε να θυμηθείτε να:
- Τεκμηριώστε πότε εκπέμπεται το σήμα και κατά πόσο εκπέμπεται πριν ή μετά από άλλα σήματα.
- Τεκμηριώστε τι μπορεί να κάνει μια εφαρμογή στον διαχειριστή σημάτων.
/** * FooWidget::foobarized: * @widget: the widget that received the signal * @foo: some foo * @bar: some bar * * The ::foobarized signal is emitted each time someone tries to foobarize @widget. */ foo_signals[FOOBARIZE] = g_signal_new ("foobarize", ...
3.3.6. Ομάδα σχολίων δομής
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { GtkWidget parent_instance; gboolean bar; } FooWidget;
Χρησιμοποιήστε το /*< private >*/ πριν από πεδία ιδιωτικών δομών που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/για την αντίστροφη συμπεριφορά.
Αν το πρώτο πεδίο είναι "g_iface", "parent_instance" ή "parent_class" θα θεωρηθεί αυτόματα ιδιωτικό και δεν θα χρειαστεί να αναφερθεί στην περιοχή των σχολίων.
Οι ομάδες σχολίων μιας δομής μπορούν επίσης να χρησιμοποιηθούν για GObjects και για GObjectClasses. Είναι συνήθως καλή ιδέα να προσθέτετε μία ομάδα σχολίου για μια κλάση, εάν έχει vmethods (γιατί έτσι μπορούν να τεκμηριωθούν). Για το ίδιο το GObject μπορείτε να χρησιμοποιήσετε τα σχετικά έγγραφα τμημάτων, έχοντας μία ξεχωριστή ομάδα για το στιγμιότυπο δομής θα ήταν χρήσιμο εάν το στιγμιότυπο έχει δημόσια πεδία. Ένα μειονέκτημα εδώ είναι ότι θα δημιουργηθούν δύο καταχωρήσεις δεικτών για το ίδιο όνομα (για την δομή και για το τμήμα).
3.3.7. Ομάδα σχολίων Enum
/** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Enum values used for the thing, to specify the thing. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something;
Χρησιμοποιήστε το /*< private >*/ πριν από ιδιωτικές τιμές enum που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/ για την αντίστροφη συμπεριφορά.