Membuat Sense of Documentation API Java - dummies

Sekali waktu, orang menilai bahasa pengaturcaraan (termasuk Java) semata-mata oleh ciri-ciri tatabahasa mereka. Adakah pernyataan jika melakukan apa yang anda harapkan? Adakah pernyataan gelung mudah digunakan? Adakah kaedah dilaksanakan dengan cekap?

Pada masa kini, perkara-perkara yang sedikit berbeza. Java mempunyai koleksi keseluruhan ciri-ciri tatabahasa, tetapi Java adalah lebih daripada sekadar aturan besar tata bahasa. Java mempunyai Standard Appl Interface Programming ication -a perpustakaan besar yang terdiri daripada lebih dari 4, 000 kelas, masing-masing dengan fungsinya sendiri, batasannya sendiri, dan peraturan sendiri untuk kegunaan yang berkesan.

Mencari istilah

Anda boleh mencari perkara dalam dokumentasi API dalam beberapa cara yang berbeza. Setiap cara mudah dalam satu keadaan atau yang lain. Sebagai contoh, Java mempunyai kaedah bernama Sistem. keluar. cetak. Apa yang berikut menerangkan dua cara untuk mencari Sistem. keluar. kaedah cetak.

Menggunakan indeks

Berikut adalah cara untuk mencari sesuatu, seperti Sistem. keluar. cetak, dengan menggunakan indeks:

Lawati dokumen. oracle. com / javase / 8 / docs / api /.
Klik pautan INDEX di bahagian atas halaman untuk membuka indeks, seperti yang ditunjukkan dalam Rajah 1.

Rajah 1: Halaman utama dokumentasi API.
Senarai huruf adalah berhampiran bahagian atas indeks (lihat Rajah 2). Klik pautan P untuk pergi ke bahagian dengan cetakan di dalamnya.

">
angka 2: Halaman indeks dokumentasi API.
Dalam bahagian P, lakukan pencarian untuk mencetak untuk mencari entri cetak.

Kebanyakan pelayar web membolehkan anda mencari sesuatu seperti println dalam teks halaman. Begini caranya:
1. Pastikan penyemak imbas mengetahui bahawa anda ingin mencari dalam bingkai besar yang memakan sebahagian besar halaman (dan bukan di bingkai yang lebih kecil di sebelah kiri halaman). Untuk melakukan ini, klik tetikus anda di dalam bingkai besar. (Jangan klik pautan. Klik pada beberapa bahagian putih yang neutral pada bingkai.)
2. Buka kotak dialog Cari pelayar. Pada kebanyakan penyemak imbas Windows, menekan Ctrl + F coaxes kotak dialog Cari dari bersembunyi. Pada Mac, mengklik Command + F melakukan silap mata.
3. Apabila anda melihat kotak dialog Cari, ketik cetakan dalam kotak teks dan klik kotak Cari atau Cari butang Ketik.
Pilih salah satu entri cetakan.

Bahagian P mempunyai beban bot besar bagi entri cetak, seperti ditunjukkan dalam Rajah 3, di bawah. Penyertaan berbeza dari satu sama lain dengan dua cara:
- Setiap entri menyatakan println (int), println (String), atau println (someOtherTypeName). Nama jenis boleh berbeza dari satu entri ke yang lain.
- Setiap entri mengatakan bahawa println adalah kaedah dalam java kelas. someStuff. someMoreStuff . Kelas boleh berbeza dari satu entri ke yang lain.
  
  entri cetak dalam indeks dokumentasi API. ">
  Rajah 3: Sesetengah penyertaan cetakan dalam indeks dokumentasi API.
Pada ketika ini, ia membayar untuk mencubit. Jika anda cuba mencetak sesuatu seperti "Hello world! ", Anda mahu salah satu entri cetakan (String). Sebaliknya, jika anda cuba mencetak nilai lengthOfStraightLine, anda mungkin akan memilih entri cetakan (berganda).

Sekarang, katakan anda telah memutuskan pada println (String). Anda boleh memilih dari tiga entri cetakan (String). Satu mengatakan ia satu kaedah di java kelas. io. PrintStream, yang seterusnya adalah kaedah di java kelas. io. PrintWriter, dan yang ketiga adalah kaedah di java kelas. sql. DriverManager. Mana antara ketiga-tiga penyertaan yang anda pilih?

Nah, apa yang sebenarnya anda cuba panggil adalah sesuatu yang bernama Sistem. keluar. cetak. Jika anda pergi melalui rigmarole keseluruhan carian dengan Systemout, anda akan mendapati Sistem itu. keluar mempunyai jenis PrintStream. (Lihat Rajah 4, di bawah.) Oleh itu, entri cetakan (String) yang anda pilih ialah

println (String) - Kaedah di java kelas. io. PrintStream. Pembolehubah

keluar mempunyai PrintStream jenis. ">
Rajah 4: Pemboleh ubah keluar mempunyai PrintStream jenis.
Klik pautan untuk entri yang telah anda pilih.

Apabila anda mengklik pautan println (String), penyemak imbas akan membawa anda ke halaman yang menerangkan kaedah cetakan, seperti yang ditunjukkan dalam Rajah 5. Halaman memberitahu anda apakah println ("Mencetak String dan kemudian …") dan menunjuk pada halaman berguna lain, seperti halaman dengan dokumentasi untuk String. Kaedah

println. ">
Rajah 5: Perihalan kaedah println.

Menggunakan senarai kelas

Berikut ialah cara mencari entri dalam API dengan memulakan dalam senarai kelas:

Lawati dokumen. oracle. com / javase / 8 / docs / api /.
Cari halaman yang mendokumenkan kelas Sistem.

Anda sedang mencari dokumentasi yang menerangkan Sistem. keluar. cetak. Jadi, tengoklah Sistem, jalankan jalan keluar, dan dari situ, jalankan cara anda untuk mencetak.

Untuk mencari pautan ke Sistem, lihat pada bingkai yang lebih rendah di sebelah kiri halaman. (Lihat Rajah 6.) Untuk mendapatkan petunjuk mengenai mencari teks pada halaman, lihat Langkah 3 di bahagian "Menggunakan indeks".

Kelas sistem. ">
Rajah 6: Mencari pautan ke kelas Sistem.
Mengklik pautan Sistem menjadikan penyemak imbas anda memaparkan halaman dokumentasi untuk kelas Sistem, seperti yang ditunjukkan dalam Rajah 7.

Dokumentasi kelas sistem. ">
angka 7: Dokumentasi kelas Sistem.
Pada halaman dokumentasi untuk kelas Sistem, cari pemboleh ubah keluar.

Jika anda menggunakan kotak dialog Cari pelayar web anda, anda perlu mengklik butang Find Next beberapa kali. (Nama keluar sangat umum, ia muncul beberapa kali dalam beberapa konteks yang berlainan di halaman dokumentasi Sistem.) Apabila anda mendapati apa yang anda cari, anda melihat jadual seperti yang ditunjukkan dalam Rajah 4, di atas.
Dalam baris jadual, klik pautan PrintStream.

Menurut dokumentasi, pembolehubah keluar merujuk kepada objek jenis PrintStream.Ini bermakna println adalah sebahagian daripada kelas PrintStream. Itulah sebabnya anda mengklik pautan PrintStream.
Pada halaman dokumentasi untuk PrintStream, cari println (String).

Anda melihat penjelasan seperti yang ditunjukkan dalam Rajah 5, di atas.

Anda boleh melakukannya juga

Setelah mengikuti langkah-langkah dalam artikel ini, anda mungkin tergoda untuk mengatakan, "Kesepakatan besar! Saya dapat mencari cetakan dalam dokumen API, tetapi saya mungkin tidak dapat mencari apa-apa lagi. Dan jika orang membuat dokumentasi untuk barangan yang mereka program sendiri, maka dokumentasi mereka tidak akan kelihatan seperti dokumentasi API standard. Saya akan naik sungai. "

Respon yang sesuai untuk bantahan tersebut adalah" Tidak masuk akal! Baloney! Balderdash! Bulu kuda! "Inilah sebabnya:

Kebanyakan helah yang anda perlukan untuk mencari sesuatu dalam dokumentasi Java standard digambarkan dalam arahan langkah demi langkah ini. Jika anda boleh mencari Sistem. keluar. cetak, anda juga boleh mencari javax. hayun. JButton atau mana-mana 4, 200 program dalam Java API standard.

Dan, apabila anda mengetahui lebih lanjut mengenai Java dan hubungan antara kelas, kaedah, dan pemboleh ubah, arahan langkah demi langkah artikel ini akan berasa lebih alami.
Dan untuk membaca dokumentasi orang lain, anda boleh menggaru masalah itu langsung dari senarai anda. Dokumen API standard tidak ditaip dengan tangan. Mereka dijana secara automatik dari kod program Java sebenar. Sebagai contoh, kod untuk PrintStream. java mempunyai beberapa baris yang kelihatan seperti ini:
```
/ ** * Cetak rentetan dan kemudian tamatkan garisan. * Kaedah ini bertindak seolah-olah ia memanggil *

{@ link #print (String)}

* dan kemudian

{@ link #println ()}

. * * @param x

String

akan dicetak. * /
```
Untuk membuat dokumentasi API, kapten Java menjalankan program yang dipanggil javadoc . Program javadoc mengambil garis seperti ini dari PrintStream. fail java dan menggunakan baris untuk membuat dokumentasi yang anda lihat dalam pelayar web anda.

Pengaturcara Java lain melakukan hal yang sama. Sebenarnya, setiap orang yang menulis kod Java menggunakan program javadoc untuk menghasilkan dokumentasi. Jadi dokumentasi Java semua kelihatan seperti dokumentasi Java yang lain. Apabila anda tahu bagaimana membaca dokumentasi API standard, anda tahu bagaimana untuk membaca dokumen Java orang lain.

Dan ya, anda boleh menggunakan program javadoc untuk membuat dokumentasi anda sendiri. Apabila anda memuat turun JDK, anda mendapat program javadoc sebagai sebahagian daripada perjanjian itu.