Αντικειμενοστραφής Προγραμματισμός, Εφαρμογές με χρήση της γλώσσας προγραμματισμού JAVA

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Java API documentation ======

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

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

Όταν μιλάμε για το Java API (Application Programming Interface), αναφερόμαστε στο interface των εργαλείων/βιβλιοθηκών που παρέχονται μαζί με τη Java. Κάποιος λοιπόν που προγραμματίζει σε Java χρειάζεται να γνωρίζει μόνο το API για να μπορεί να χρησιμοποιήσει τις διαθέσιμες βιβλιοθήκες, frameworks, κτλ.  Το API documentation είναι ένα κείμενο το οποίο περιέχει μια περιγραφή του API. Ως παράδειγμα, δείτε  [[ https://docs.oracle.com/javase/8/docs/api/index.html | το API documentation της τρέχουσας έκδοσης Java]]

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

Ακολουθούν μερικές οδηγίες και παραδείγματα. Μπορείτε να βρείτε περισσότερες πληροφορίες και παραδείγματα στον [[ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html | οδηγό του εργαλείου javadoc της Oracle]].

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

<code java>
/** 
 *   Represents a 2D rectangle.
 */

public class Rectangle {
  ...
}
</code>

Απαγορεύεται να παρεμβάλλεται κάτι ανάμεσα στο σχόλιο και την αρχή της οντότητας στην οποία αναφέρεται:
<WRAP important 80% center round>
<code java>
/** 
 *   Represents a 2D rectangle.
 */

import java.util.Scanner;  // <=== ΛΑΘΟΣ!!!

public class Rectangle {
  ...
}
</code>
</WRAP>

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

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

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

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

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

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

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

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

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

===== Παράδειγμα =====
Μπορείτε να δείτε ένα απλό παράδειγμα συγγραφής σχολίων τύπου javadoc στον κώδικα που παρουσιάστηκε στο [[ :2015-2016:lab:lab2example | δεύτερο εργαστήριο. ]]

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

Το αποτέλεσμα θα είναι [[ http://inf-server.inf.uth.gr/courses/MEPA21/lab_examples/lab2_javadoc/index.html | αυτό το documentation ]]
Αντικειμενοστραφής Προγραμματισμός, Εφαρμογές με χρήση της γλώσσας προγραμματισμού JAVA

User Tools

Site Tools

Page Tools
