Java API documentation

Κάθε σύγχρονη γλώσσα υψηλού επιπέδου παρέχει κάποιες βασικές δομές και λειτουργίες, και συνήθως περιλαμβάνει ένα σύνολο από βιβλιοθήκες και εργαλεία για επιπλέον λειτουργίες. Αυτές οι βιβλιοθήκες έχουν υλοποιηθεί από κάποιους προγραμματιστές, έχουν γίνει μέρος της Java και μπορεί να τις χρησιμοποιήσει οποιοσδήποτε γράφει κώδικα Java.

Ο χρήστης μιας βιβλιοθήκης δε χρειάζεται να γνωρίζει πώς αυτή έχει υλοποιηθεί αλλά μόνο πώς μπορεί να χρησιμοποιήσει τα εργαλεία που του παρέχει. Για παράδειγμα, αν δουλεύετε με αντικείμενα τύπου String και θέλετε να συγκρίνετε δύο από αυτά, σας αρκεί να γνωρίζετε ότι υπάρχει γι αυτό μια μέθοδος που λέγεται compareTo, τι παραμέτρους παίρνει, και τι επιστρέφει. Δε σας ενδιαφέρει πώς έχει υλοποιηθεί εσωτερικά η compareTo. Με άλλα λόγια αυτό που χρειάζεται να γνωρίζετε ήταν το interface - τη διεπαφή ανάμεσα στη βιβλιοθήκη κι εσάς (το χρήστη).

Όταν μιλάμε για το Java API (Application Programming Interface), αναφερόμαστε στο interface των εργαλείων/βιβλιοθηκών που παρέχονται μαζί με τη Java. Κάποιος λοιπόν που προγραμματίζει σε Java χρειάζεται να γνωρίζει μόνο το API για να μπορεί να χρησιμοποιήσει τις διαθέσιμες βιβλιοθήκες, frameworks, κτλ. Το API documentation είναι ένα κείμενο το οποίο περιέχει μια περιγραφή του API. Ως παράδειγμα, δείτε το API documentation της τρέχουσας έκδοσης Java

Το API documentation συντάσσεται με τυποποιημένο τρόπο για να υπάρχει συνέπεια και να διατηρείται συγκεκριμένο επίπεδο ποιότητας. Για να διευκολυνθεί η συγγραφή του υπάρχει ένα εργαλείο που λέγεται javadoc το οποίο διαβάζει πηγαίο κώδικα Java και ειδικά διαμορφωμένα σχόλια και παράγει API documentation.

Ακολουθούν μερικές οδηγίες και παραδείγματα. Μπορείτε να βρείτε περισσότερες πληροφορίες και παραδείγματα στον οδηγό του εργαλείου javadoc της Oracle.

Τα σχόλια javadoc περικλείονται ανάμεσα σε και τοποθετούνται ακριβώς πριν από κάθε κλάση, μέθοδο, πεδίο και constructor (από εδώ και στο εξής θα χρησιμοποιούμε τον όρο “οντότητα” γι'αυτά). Για παράδειγμα:

/** 
 *   Represents a 2D rectangle.
 */
 
public class Rectangle {
  ...
}

Απαγορεύεται να παρεμβάλλεται κάτι ανάμεσα στο σχόλιο και την αρχή της οντότητας στην οποία αναφέρεται:

/** 
 *   Represents a 2D rectangle.
 */
 
import java.util.Scanner;  // <=== ΛΑΘΟΣ!!!
 
public class Rectangle {
  ...
}

Η πρώτη πρόταση πρέπει να είναι μια σύντομη περιγραφή της οντότητας. Το javadoc θεωρεί ότι αυτή η σύντομη περιγραφή τελειώνει στην πρώτη τελεία η οποία ακολουθάται από κενό, ή tab, ή enter, ή κάποιο tag.

Τα tags χρησιμοποιούνται για να προσδιορίσουν συγκεκριμένες πληροφορίες όπως το όνομα του προγραμματιστή, τις παραμέτρους μιας μεθόδου κτλ. Τυπικά tags είναι τα παρακάτω:

• @author όνομα_συγγραφέα
  Το όνομα του προγραμματιστή που έγραψε τον κώδικα. Χρησιμοποιείται σε σχόλια κλάσεων.

• @param όνομα_παραμέτρου περιγραφή_παραμέτρου
  Χρησιμοποιείται σε σχόλια μεθόδων. Αν υπάρχουν πολλές παράμετροι, χρησιμοποιήστε πολλαπλά tags @param με τη σειρά που εμφανίζονται οι παράμετροι στο πρωτότυπο της μεθόδου.

• @return περιγραφή_της_ποσότητας_που_επιστρέφει_η_μέθοδος
  Χρησιμοποιείται σε σχόλια μεθόδων οι οποίες επιστρέφουν κάποια τιμή. Δε χρησιμοποιείται αν μια μέθοδος έχει void τύπο επιστροφής.

• @throws τύπος_Exception περιγραφή
  Χρησιμοποιείται σε σχόλια μεθόδων που πετάνε unchecked exceptions

• { @literal κείμενο}
  Περικλείει κείμενο το οποίο διαφορετικά μπορεί να ερμηνευθεί με τρόπο που δε θέλουμε (πχ, τελεία που δε θέλουμε να τερματίσει το σχόλιο, σύμβολα που έχουν συγκεκριμένη ερμηνεία σε html, κτλ.)

• { @code κώδικας }
  Περικλείει μικρά κομμάτια κώδικα

• Επιπλέον, μπορείτε να χρησιμοποιείτε html tags.

Μπορείτε να δείτε ένα απλό παράδειγμα συγγραφής σχολίων τύπου javadoc στον κώδικα που παρουσιάστηκε στο πρώτο εργαστήριο.

Για να παράγετε documentation για ένα project στο Netbeans, κάντε δεξί-κλικ στο όνομα του project σας και επιλέξτε generate javadoc.

Το αποτέλεσμα για τον κώδικα του πρώτου εργαστηρίου θα είναι αυτό το documentation