Τεκμηρίωση συμβόλων
Κάθε σύμβολο (συνάρτηση, μακροεντολή, δομή, αρίθμηση, σήμα, ιδιότητα) τεκμηριώνεται σε ξεχωριστό μπλοκ. Η καταλληλότερη θέση για τα μπλοκ είναι δίπλα στους ορισμούς των συμβόλων, γιατί διευκολύνει το έργο συγχρονισμού. Επομένως, η τεκμηρίωση των συναρτήσεων συνήθως βρίσκεται στο αρχείο του πηγαίου κώδικα, ενώ των μακροεντολών, δομών και αριθμήσεων στο αρχείο κεφαλίδας.
- 3.3.1. Γενικές ετικέτες
- 3.3.2. Μπλοκ σχολίου συνάρτησης
- 3.3.3. Μπλοκ σχολίου ιδιότητας
- 3.3.4. Μπλοκ σχολίου σήματος
- 3.3.5. Μπλοκ σχολίου δομής
- 3.3.6. Μπλοκ σχολίου Enum
3.3.1. Γενικές ετικέτες
Μπορείτε να προσθέσετε πληροφορίες εκδόσεων σε όλα τα στοιχεία της τεκμηρίωσης για να πείτε πότε εισήχθηκε ένα API, ή πότε καταργήθηκε.
- Since:
-
Περιγραφή για ποια έκδοση του κώδικα είναι διαθέσιμο το API.
- Deprecated:
-
Παράγραφος που ενημερώνει ότι θα πρέπει να σταματήσει η χρήση της συνάρτησης. Η περιγραφή θα πρέπει να παραπέμπει τον αναγνώστη στο νέο API.
(FIXME : Πληροφορίες σταθερότητας)
/** * foo_get_bar: * @foo: some foo * * Ανάκτηση του @foo's bar. * * Επιστρέφει: @foo's bar * * Από το: 2.6 * Παρωχημένο: 2.12: Χρησιμοποιείστε το foo_baz_get_bar() στη θέση του. */ Bar * foo_get_bar(Foo *foo) { ...
3.3.2. Μπλοκ σχολίου συνάρτησης
Παρακαλούμε να θυμηθείτε να:
- Τεκμηριώσετε κατά πόσο τα επιστρεφόμενα αντικείμενα, λίστες, συμβολοσειρές, κ.λπ, θα πρέπει να ελευθερώνονται, να μην ελευθερώνονται ή να απορρίπτονται.
- Τεκμηριώσετε κατά πόσο οι παράμετροι μπορούν να είναι μηδενικές (NULL) και τι συμβαίνει αν είναι.
- Αναφέρετε ενδιαφέρουσες προ-υποθέσεις και μετα-υποθέσεις όπου χρειάζεται.
Το Gtk-doc θεωρεί ότι όλα τα σύμβολα (μακροεντολές, συναρτήσεις, κτλ.) που ξεκινούν με '_' είναι ιδιωτικά και τα μεταχειρίζεται σαν στατικές συναρτήσεις.
Επίσης, ρίξτε μια ματιά στις ετικέτες σημείωσης ενδοσκόπησης: http://live.gnome.org/GObjectIntrospection/Annotations
/** * 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. */
- Returns:
-
Παράγραφος που περιγράφει το επιστρεφόμενο αποτέλεσμα.
- @...:
-
Σε περίπτωση που η μεταβλητή μπορεί να δεκτεί μεταβλητό αριθμό ορισμάτων (variadic), πρέπει να χρησιμοποιήσετε αυτή την ετικέτα (η ετικέτα @Varargs: λειτουργεί επίσης, για ιστορικούς λόγους).
3.3.3. Μπλοκ σχολίου ιδιότητας
/** * SomeWidget:some-property: * * Here you can document a property. */ g_object_class_install_property (object_class, PROP_SOME_PROPERTY, ...);
3.3.4. Μπλοκ σχολίου σήματος
Παρακαλούμε να θυμηθείτε να:
- Τεκμηριώστε πότε εκπέμπεται το σήμα και αν εκπέμπεται πριν ή μετά από άλλα σήματα.
- Τεκμηριώστε τι μπορεί να κάνει μια εφαρμογή στον διαχειριστή σημάτων.
/** * 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.5. Μπλοκ σχολίου δομής
/** * FooWidget: * @bar: some #gboolean * * This is the best widget, ever. */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
Χρησιμοποιήστε το /*< private >*/ πριν από πεδία ιδιωτικών δομών που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/για την αντίστροφη συμπεριφορά.
Οι ομάδες σχολίων μιας Δομής μπορούν επίσης να χρησιμοποιηθούν για GObjects και για GObjectClasses. Είναι συνήθως καλή ιδέα να προσθέτετε μία ομάδα σχολίου για μια κλάση, εάν έχει vmethods (γιατί έτσι μπορούν να τεκμηριωθούν). Για το ίδιο το GObject μπορείτε να χρησιμοποιήσετε τα σχετικά έγγραφα τμημάτων, έχοντας μία ξεχωριστή ομάδα για το στιγμιότυπο δομής θα ήταν χρήσιμο εάν το στιγμιότυπο έχει δημόσια πεδία. Ένα μειονέκτημα εδώ είναι ότι θα δημιουργηθούν δύο καταχωρήσεις δεικτών για το ίδιο όνομα (για την δομή και για το τμήμα).
3.3.6. Μπλοκ σχολίου Enum
/** * Something: * @SOMETHING_FOO: something foo * @SOMETHING_BAR: something bar * * Τιμές απαρίθμησης χρησιμοποιούνται για το πράγμα, για τον ορισμό του πράγματος. */ typedef enum { SOMETHING_FOO, SOMETHING_BAR, /*< private >*/ SOMETHING_COUNT } Something·
Χρησιμοποιήστε το /*< private >*/ πριν από ιδιωτικές τιμές enum που θέλετε να αποκρύψετε. Χρησιμοποιήστε το /*< public >*/ για την αντίστροφη συμπεριφορά.