Συμβατά σχόλια με το εργαλείο javadoc

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

Για αυτό, ξεκινήστε να βάζετε σχόλια. Όχι όμως οποιαδήποτε σχόλια, αλλά σχόλια που θα σας επιτρέψουν να εξάγετε και html σελίδες, όπως το ωραιότατο JavaAPI.

Θα χρειαστείτε το εργαλείο javadoc, το οποίο έρχεται μαζί με το Java2 SDK.

HTML formatting

Στα συμβατά με javadoc σχόλια μπορεί να εμφανίζονται οποιεσδήποτε νόμιμες HTML ετικέτες, όπως για παράδειγμα οι <p>, <b>...</b> κλπ.

Επιπλέον, με το

<code>mplah</code>

το κείμενο mplah εμφανίζεται σαν monospaced κείμενο.

Τέλος, χρησιμοποιώντας το

<blockquote><pre>new Something</prec></blockquote>

δημιουργεί έντονο, monospaced κείμενο.

Σύνοψη και τεκμηρίωση εφαρμογών - πακέτων

Γράψτε σελίδες HTML για να παρέχετε κάποια σύνοψη πακέτων και εφαρμογών. Όμως προσοχή, μόνον το κείμενο μεταξύ των tags <body> και </body> λαμβάνεται υπόψην.

Για την τεκμηρίωση βιβλιοθηκών/εφαρμογών το αρχείο είναι καλύτερο να ονομάζεται overview.html και να βρίσκεται πριν από οτιδήποτε άλλο στον κατάλογο. Πρέπει να περιέχει περιγραφή της βιβλιοθήκης ή της εφαρμογής και πως χρησιμοποιείται.

Για τεκμηρίωση πακέτων, χρησιμοποιούνται αρχεία με όνομα package.html και πρέπει να βρίσκονται στον ίδιο κατάλογο με τον πηγαίο κώδικα του πακέτου. ΠΡΟΣΟΧΗ: μια και το javadoc χρησιμοποιεί την πρώτη πρόταση για να δημιουργήσει μια σύνοψη, μην χρησιμοποιείτε άλλα tags στην πρώτη πρόταση.
Στο package.html μπορούν να υπάρχουν και javadoc tags όπως @since που υποδηλώνει πότε δημιουργήθηκε το πακέτο και @deprecated που σημαίνει ότι το πακέτο αυτό σύντομα θα αφαιρεθεί και θα αντικατασταθεί από κάποιο άλλο, καθώς και ένα σύνδεσμο προς το πακέτο που αντικαθιστά την λειτουργικότητά του.

Τεκμηρίωση κώδικα

Το javadoc αναγνωρίζει μόνον σχόλια της μορφής:

/** mplah mplah mplah */

Το παρακάτω είναι απόλυτα νόμιμο:

/** This is a method */
public static void method() { }

Ενώ τα:

/* This is something */
public static void method() {
	...
}

και

public static void method2() {
	/** comment */
}

δεν αναγνωρίζονται από το javadoc και άρα δεν εμφανίζονται στην παραγόμενη τεκμηρίωση.

Τεκμηρίωση κλάσεων

Τα σχόλια πρέπει να μπαίνουν μετά από τις δηλώσεις για πακέτο (package ...) και τα imports. Η πιο συνηθισμένη πρακτική είναι να είναι ακριβώς πριν την δήλωση της κλάσης.

/**

 * This is a class that does something useful.
 *
 * @author  You (you@yourplace.you)
 * @version 1.0
 * @see     java.util.Random#nextDouble()
 */

Ετικέτα	Περιγραφή
@author	Ο συγγραφέας της κλάσης.
@version	Έκδοση της κλάσης.
@since	Περιγράφει πότε εμφανίστηκε αυτή η κλάση. Μπορεί να είναι ημερομηνία ή έκδοση.
@link	Παρέχει έναν σύνδεσμο προς κάποιο URL, κάποια κλάση ή σε κάποια μέθοδο.
@see	Το ίδιο με παραπάνω, αλλά βάζει τους συνδέσμους κάτω από τν τίτλο "See Also".

Τεκμηρίωση μεθόδων

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

Ετικέτα	Περιγραφή
@param	Περιγράφει κάποια από τις παραμέτρους τις μεθόδου και τις νόμιμες τιμές της. Αυτή η ετικέτα ακολουθείται από το όνομα της παραμέτρου, όπως εμφανίζεται στην δήλωση της μεθόδου, και την περιγραφή της.
@return	Περιγράφει την τιμή που επιστρέφεται. Καλύτερα είναι να περιγράφονται και τα όρια των τιμών και το πότε επιστρέφεται κάθε τιμή.
@throws, @exception	Περιγράφει ποια exception μπορεί να προκαλέσει η μέθοδος και για ποιον λόγο. Η ετικέτα ακολουθείται από τον τύπο της exception και την περιγραφή για τον λόγο που μπορεί να προκύψει.
@link	Παρέχει έναν σύνδεσμο προς κάποιο URL, κάποια κλάση ή σε κάποια μέθοδο.
@see	Το ίδιο με παραπάνω, αλλά βάζει τους συνδέσμους κάτω από τν τίτλο "See Also".
@since	Περιγράφει πότε εμφανίστηκε αυτή η μέθοδος. Μπορεί να είναι ημερομηνία ή έκδοση.

Σύνδεσμοι σε e-mail, εικόνες και άλλα αρχεία

Εάν χρειάζονται σύνδεσμοι προς εικόνες, e-mail διευθύνσεις ή οποιοδήποτε άλλο τύπο αρχείου, αυτό γίνεται εύκολα χρησιμοποιώντας τις κλασσικές ετικέτες HTML.

Απλώς, δημιουργήστε τον υποκατάλογο doc-files σε κάθε πακέτο που έχει κλάσεις ή μεθόδους σε κάποια αρχεία, και τοποθετήστε τα αρχεία σε αυτόν τον κατάλογο.

Παράδειγμα:

/**
 * An example
 * <P>
 * <a href="doc-files/code_example.java">This is the code example</a>
 * <img src="doc-files/image.gif">This is just a simple image</a>
 * @author <a href="mailto:me@myHouse.myCountry">Your name</a>
 */

ipapadop