Κάνοντας την Τεκμηρίωση API της Sense of Java

Μια φορά κι έναν καιρό, οι άνθρωποι κρίνουν γλώσσες προγραμματισμού (συμπεριλαμβανομένης της Java) μόνο με τα γραμματικά χαρακτηριστικά τους. Η εντολή if κάνει αυτό που περιμένετε να κάνει; Είναι εύχρηστες οι δηλώσεις βρόχου; Οι μέθοδοι υλοποιούνται αποτελεσματικά;

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

Αναζήτηση για έναν όρο

Μπορείτε να βρείτε πράγματα στην τεκμηρίωση API με διάφορους τρόπους. Κάθε τρόπος είναι βολικός σε μια ή την άλλη κατάσταση. Για παράδειγμα, η Java έχει μια μέθοδο που ονομάζεται System. έξω. println. Αυτό που ακολουθεί περιγράφει δύο τρόπους για να αναζητήσετε το Σύστημα. έξω. μέθοδος println.

Χρήση του ευρετηρίου

Δείτε πώς μπορείτε να βρείτε κάτι, όπως το σύστημα. έξω. println, χρησιμοποιώντας το ευρετήριο:

1. Επισκεφθείτε έγγραφα. μαντείο. com / javase / 8 / docs / api /.

2. Κάντε κλικ στο σύνδεσμο INDEX στο επάνω μέρος της σελίδας για να ανοίξετε το ευρετήριο, όπως φαίνεται στο σχήμα 1.

   

   Εικόνα 1: Η κύρια σελίδα της τεκμηρίωσης του API.

   Μια λίστα γραμμάτων βρίσκεται κοντά στο επάνω μέρος του ευρετηρίου (βλ. Εικόνα 2). Κάντε κλικ στο σύνδεσμο P για να μεταβείτε στην ενότητα με println σε αυτό.

   

   ">
   εικόνα 2: Η σελίδα ευρετηρίου της τεκμηρίωσης API.

3. Στην ενότητα P, πραγματοποιήστε αναζήτηση για το println για να βρείτε τις καταχωρήσεις println.

   Τα περισσότερα προγράμματα περιήγησης στο Web σάς επιτρέπουν να αναζητήσετε κάτι σαν το println στο κείμενο μιας σελίδας. Δείτε πώς:

   1. Βεβαιωθείτε ότι το πρόγραμμα περιήγησης γνωρίζει ότι θέλετε να κάνετε αναζήτηση στο μεγάλο πλαίσιο που καταλαμβάνει το μεγαλύτερο μέρος της σελίδας (και όχι στα μικρότερα πλαίσια στην αριστερή πλευρά της σελίδας). Για να το κάνετε αυτό, κάντε κλικ στο ποντίκι σας μέσα στο μεγάλο πλαίσιο. (Κάντε κλικ σε μια ουδέτερη λευκή περιοχή του πλαισίου.)

   2. Ανοίξτε το παράθυρο διαλόγου Εύρεση του προγράμματος περιήγησης. Στα περισσότερα προγράμματα περιήγησης των Windows, πατώντας τα πλήκτρα Ctrl + F συγχωνεύεται το παράθυρο διαλόγου "Εύρεση" από την απόκρυψη. Σε Mac, κάνοντας κλικ στο Command + F, το κόλπο.

   3. Όταν βλέπετε το παράθυρο διαλόγου Εύρεση, πληκτρολογήστε println στο πλαίσιο κειμένου και κάντε κλικ στο κουτί Εύρεση ή Εύρεση επόμενου.

4. Επιλέξτε μία από τις καταχωρήσεις println.

   Το τμήμα P έχει ένα μεγάλο φορτίο πλοίων από καταχωρήσεις println, όπως φαίνεται στο σχήμα 3, παρακάτω. Οι καταχωρήσεις διαφέρουν μεταξύ τους με δύο τρόπους:

   • Κάθε καταχώρηση λέει println (int), println (String) ή println (someOtherTypeName). Το όνομα του τύπου μπορεί να διαφέρει από μία καταχώρηση σε άλλη.

   • Κάθε καταχώρηση λέει ότι η println είναι μια μέθοδος στην Java java. someStuff. someMoreStuff . Η κλάση μπορεί να διαφέρει από τη μια καταχώρηση στην άλλη.

     

     καταχωρήσεις println στο ευρετήριο της τεκμηρίωσης API. ">
     Εικόνα 3: Ορισμένες καταχωρήσεις println στο ευρετήριο της τεκμηρίωσης του API.

   Σε αυτό το σημείο, πληρώνει για να περιπλανηθεί. Εάν προσπαθείτε να εκτυπώσετε κάτι σαν "Γεια σας κόσμος! ", Θέλετε μία από τις καταχωρήσεις println (String). Από την άλλη πλευρά, αν προσπαθείτε να εκτυπώσετε την τιμή του lengthOfStraightLine, πιθανότατα θα επιλέξετε μια εγγραφή println (διπλή).

   Τώρα, ας υποθέσουμε ότι έχετε αποφασίσει για println (String). Μπορείτε να επιλέξετε από τρεις καταχωρήσεις println (String). Κάποιος λέει ότι είναι μια μέθοδος στην τάξη java. io. Το PrintStream, το επόμενο είναι μια μέθοδος στην Java. io. PrintWriter, και το τρίτο είναι μια μέθοδος στην Java java. sql. DriverManager. Ποια από αυτές τις τρεις καταχωρίσεις επιλέγετε;

   Λοιπόν, αυτό που πραγματικά προσπαθείτε να καλέσετε είναι κάτι που ονομάζεται System. έξω. println. Εάν περάσετε ολόκληρη την αναζήτηση με το Systemout, θα βρείτε αυτό το σύστημα. out έχει τύπο PrintStream. (Βλ. Εικόνα 4, παρακάτω.) Έτσι, η καταχώρηση println (String) που αποφασίζετε να επιλέξετε είναι

   println (String) - Μέθοδος στην κλάση java. io. PrintStream.

   

   η μεταβλητή έχει τον τύπο PrintStream. ">
   Εικόνα 4: Η μεταβλητή out έχει τύπο PrintStream.

5. Κάντε κλικ στο σύνδεσμο για την καταχώρηση που έχετε επιλέξει.

   Όταν κάνετε κλικ στον σύνδεσμο println (String), το πρόγραμμα περιήγησης σας μεταφέρει σε μια σελίδα που εξηγεί μια μέθοδο println, όπως φαίνεται στο σχήμα 5. Η σελίδα σας λέει τι κάνει println ("Print a String and then …" δείχνει σε άλλες χρήσιμες σελίδες, όπως η σελίδα με την τεκμηρίωση για το String.

   

   μέθοδος println. ">
   Εικόνα 5: Περιγραφή της μεθόδου println.

Χρήση της λίστας κατηγοριών

Δείτε πώς μπορείτε να βρείτε μια καταχώρηση στο API ξεκινώντας από τη λίστα των κατηγοριών:

1. Επισκεφτείτε τα αρχεία. μαντείο. com / javase / 8 / docs / api /.

2. Βρείτε τη σελίδα που τεκμηριώνει την κλάση του συστήματος.

   Ψάχνετε για τεκμηρίωση που εξηγεί το σύστημα. έξω. println. Έτσι κοιτάζετε το σύστημα, εργάζεστε στο δρόμο σας, και από εκεί εργάζεστε στο println.

   Για να βρείτε μια σύνδεση με το σύστημα, κοιτάξτε στο κατώτερο πλαίσιο στην αριστερή πλευρά της σελίδας. (Βλ. Εικόνα 6.) Για συμβουλές σχετικά με την εύρεση κειμένου στη σελίδα, ανατρέξτε στο Βήμα 3 στην ενότητα "Χρήση του ευρετηρίου".

   

   Κατηγορία συστήματος. ">
   Εικόνα 6: Εύρεση συνδέσμου προς την κλάση του συστήματος.

   Κάνοντας κλικ στο σύνδεσμο System, το πρόγραμμα περιήγησης εμφανίζει τη σελίδα τεκμηρίωσης για την κλάση System, όπως φαίνεται στο σχήμα 7.

   

   Τεκμηρίωση της κλάσης συστήματος. ">
   Εικόνα 7: Τεκμηρίωση της κλάσης του συστήματος.

3. Στη σελίδα τεκμηρίωσης για την κλάση System, εντοπίστε τη μεταβλητή out.

   Εάν χρησιμοποιείτε το παράθυρο διαλόγου Εύρεση του προγράμματος περιήγησης στο Web, πρέπει να κάνετε κλικ στο κουμπί Εύρεση επόμενου φορά αρκετές φορές. (Το όνομα είναι τόσο συνηθισμένο, εμφανίζεται αρκετές φορές σε διάφορα διαφορετικά περιβάλλοντα στη σελίδα τεκμηρίωσης συστήματος.) Όταν βρείτε αυτό που ψάχνετε, βλέπετε έναν πίνακα όπως αυτόν που φαίνεται στο σχήμα 4 παραπάνω.

4. Στην εξωτερική σειρά του πίνακα, κάντε κλικ στο σύνδεσμο PrintStream.

   Σύμφωνα με την τεκμηρίωση, η μεταβλητή out αναφέρεται σε ένα αντικείμενο τύπου PrintStream.Αυτό σημαίνει ότι το println είναι μέρος της κλάσης PrintStream. Γι 'αυτό κάνετε κλικ στο σύνδεσμο PrintStream.

5. Στη σελίδα τεκμηρίωσης για το PrintStream, βρείτε println (String).

   Βλέπετε μια εξήγηση όπως αυτή που παρουσιάζεται στο Σχήμα 5, παραπάνω.

Μπορείτε επίσης να το κάνετε

Αφού ακολουθήσετε τα βήματα αυτού του άρθρου, ίσως μπείτε στον πειρασμό να πείτε: "Μεγάλη υπόθεση! Μπορώ να βρω println στα έγγραφα API, αλλά πιθανότατα δεν μπορώ να βρω κάτι άλλο. Και αν οι άνθρωποι δημιουργήσουν τεκμηρίωση για πράγματα που προγραμματίζουν μόνοι τους, τότε η τεκμηρίωσή τους δεν θα μοιάζει με την τυπική τεκμηρίωση του API. Θα είμαι ένας ρυάκι. "

Η κατάλληλη απάντηση σε μια τέτοια αντίρρηση είναι" ανοησίες! Ανοησία! Ανοησίες! ΦΤΕΡΑ ΑΛΟΓΟΥ! "Εδώ είναι:

• Τα περισσότερα από τα κόλπα που χρειάζεστε για την εύρεση στοιχείων στην τυπική τεκμηρίωση Java απεικονίζονται στις οδηγίες βήμα προς βήμα αυτού του άρθρου. Αν μπορείτε να βρείτε το σύστημα. έξω. println, μπορείτε επίσης να βρείτε javax. κούνια. JButton ή οποιοδήποτε από τα 4, 200 προγράμματα στο πρότυπο Java API.

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

• Όσον αφορά την τεκμηρίωση της τεκμηρίωσης άλλων ανθρώπων, μπορείτε να το μηδενίσετε από τη λίστα σας. Τα τυπικά έγγραφα API δεν πληκτρολογούνται με το χέρι. Δημιουργήθηκαν αυτόματα από τον τρέχοντα κώδικα προγράμματος Java. Για παράδειγμα, ο κώδικας για το PrintStream. η java έχει μερικές γραμμές που μοιάζουν με αυτό:

  / ** * Εκτυπώστε μια συμβολοσειρά και στη συνέχεια τερματίστε τη γραμμή. * Αυτή η μέθοδος συμπεριφέρεται σαν να επικαλείται *
  
  {@ link #print (String)}
  
  * και στη συνέχεια
  
  {@ link #println ()}
  
  . * * @param x Το
  
  String
  
  που θα εκτυπωθεί. * /
  

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

  Άλλοι προγραμματιστές Java κάνουν το ίδιο πράγμα. Στην πραγματικότητα, όλοι όσοι γράφουν κώδικα Java χρησιμοποιούν το πρόγραμμα javadoc για τη δημιουργία τεκμηρίωσης. Έτσι, η τεκμηρίωση Java του καθενός μοιάζει με την τεκμηρίωση Java όλων των άλλων. Όταν γνωρίζετε τον τρόπο με τον οποίο μπορείτε να διαβάσετε την τυπική τεκμηρίωση του API, γνωρίζετε πώς να διαβάσετε τα έγγραφά σας Java για το σπίτι.

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