PHPDocumentor adalah alat yang ditulis dalam PHP. Untuk program PHP dengan anotasi standar, alat ini dapat dengan cepat menghasilkan dokumen API dengan referensi silang, pengindeksan, dan fungsi lainnya. Versi lama adalah phpdoc.
1. Apa itu phpDocumentor?
PHPDocumentor adalah alat yang ditulis dalam PHP. Untuk program PHP dengan anotasi standar, alat ini dapat dengan cepat menghasilkan dokumen API dengan referensi silang, pengindeksan, dan fungsi lainnya. Versi lama adalah phpdoc. Mulai dari 1.3.0, telah diubah namanya menjadi phpDocumentor. Versi baru menambahkan dukungan untuk sintaks php5. Pada saat yang sama, dokumen dapat dibuat dengan mengoperasikan browser klien, dan dokumen dapat dikonversi ke PDF, HTML, Ada beberapa bentuk CHM yang sangat nyaman.
Ketika PHPDocumentor berfungsi, ia akan memindai kode sumber PHP di bawah direktori yang ditentukan, memindai kata kunci, mencegat komentar yang perlu dianalisis, kemudian menganalisis tag khusus di komentar, menghasilkan file xml, dan kemudian berdasarkan informasi dari kelas dan modul yang dianalisis, membuat indeks yang sesuai, menghasilkan file xml, dan menggunakan templat yang disesuaikan untuk menghasilkan file dalam format yang ditentukan untuk file xml yang dihasilkan.
2. Instal phpDocumentor
Seperti modul lain di bawah pir, instalasi phpDocumentor juga dibagi menjadi dua metode: instalasi otomatis dan instalasi manual Kedua metode ini sangat mudah:
A. Instal secara otomatis melalui pir dan masuk pada baris perintah
pir instal PhpDocumentor
B. Instal secara manual versi terbaru PhpDocumentor (sekarang 1.4.0) di http://manual.phpdoc.org/ dan unzip kontennya.
3． Cara menggunakan PhpDocumentor untuk menghasilkan baris perintah dokumentasi:
Di direktori tempat phpDocumentor berada, masukkan
Php-h
Anda akan mendapatkan daftar parameter rinci, beberapa parameter penting di antaranya adalah sebagai berikut:
-f Nama file yang akan dianalisis, beberapa file dipisahkan dengan koma
-d Direktori yang akan dianalisis, beberapa direktori dipisahkan dengan koma
-t jalur penyimpanan dokumen yang dihasilkan
-o Format dokumen keluaran, strukturnya adalah format keluaran: nama konverter: direktori templat.
Misalnya: phpdoc -o HTML:frames:earthli -f test.php -t docs
Antarmuka web dibuat di phpdoc baru. Selain membuat dokumen di baris perintah, Anda juga dapat membuat dokumen di browser klien. Metode spesifiknya adalah dengan menempatkan konten PhpDocumentor terlebih dahulu di direktori apache diakses melalui browser, antarmuka berikut akan ditampilkan setelah akses:
Klik tombol file untuk memilih file atau folder php yang akan diproses. Anda juga dapat mengabaikan pemrosesan file tertentu dengan menentukan File untuk diabaikan di antarmuka ini.
Kemudian klik tombol keluaran untuk memilih jalur penyimpanan dan format dokumen yang dihasilkan.
Terakhir, klik buat, dan phpdocumentor akan secara otomatis mulai membuat dokumen. Kemajuan dan status pembuatan akan ditampilkan di bagian bawah.
Total Waktu Dokumentasi: 1 detik
Selesai
Operasi Selesai!!
Kemudian, kita dapat melihat dokumen yang dihasilkan. Jika dalam format pdf, nama defaultnya adalah dokumentasi.pdf.
4. Tambahkan komentar standar ke kode php
PHPDocument menghasilkan dokumen dari komentar di kode sumber Anda, jadi proses mengomentari program Anda juga merupakan proses kompilasi dokumentasi.
Dari sudut pandang ini, PHPdoc mendorong Anda untuk mengembangkan kebiasaan pemrograman yang baik dan mencoba menggunakan spesifikasi dan teks yang jelas untuk membubuhi keterangan pada program Anda, pada saat yang sama, ini sedikit banyak menghindari beberapa masalah ketidaksinkronan antara persiapan dokumen dan dokumen pembaruan setelahnya.
Di phpdocumentor, komentar dibagi menjadi komentar dokumentasi dan komentar non-dokumentasi.
Yang disebut komentar dokumentasi adalah komentar multi-baris yang ditempatkan di depan kata kunci tertentu.Kata kunci tertentu mengacu pada kata kunci yang dapat dianalisis dengan phpdoc, seperti class, var, dll. Untuk lebih jelasnya silakan lihat Lampiran 1.
Komentar yang tidak mendahului kata kunci atau tidak terstandarisasi disebut komentar non-dokumentasi. Komentar ini tidak akan dianalisis oleh phpdoc dan tidak akan muncul di teks API yang Anda hasilkan.
3.2 Cara menulis komentar dokumentasi:
Semua komentar dokumentasi adalah komentar multi-baris yang dimulai dengan /**, yang disebut DocBlock di phpDocumentor. DocBlock mengacu pada informasi bantuan tentang kata kunci tertentu yang ditulis oleh pengembang perangkat lunak sehingga orang lain dapat mengetahui tujuan spesifik kata kunci tersebut dan cara menggunakannya. PhpDocumentor menetapkan bahwa DocBlock berisi informasi berikut:
1. Fungsi deskripsi singkat area
2. Detil Deskripsi daerah
3. Tandai
Baris pertama komentar dokumentasi adalah area deskripsi fungsi. Teks tersebut umumnya menjelaskan secara singkat fungsi kelas, metode, atau fungsi ini. Teks deskripsi fungsi akan ditampilkan di area indeks dalam dokumen yang dihasilkan. Isi area deskripsi fungsi dapat diakhiri dengan baris kosong atau. Setelah area deskripsi fungsi adalah baris kosong, diikuti dengan area deskripsi detail. Anda juga bisa Contoh penggunaan, dll. Di bagian ini, Anda harus fokus pada memperjelas tujuan umum dan penggunaan fungsi atau metode API Anda, dan menunjukkan apakah itu lintas platform (jika terlibat). Untuk informasi terkait platform, Anda harus memperlakukannya secara berbeda dari informasi umum. pendekatan yang biasa dilakukan adalah memulai baris baru, dan kemudian menulis tindakan pencegahan atau informasi khusus pada platform tertentu. Informasi ini harus cukup sehingga pembaca Anda dapat menulis informasi pengujian yang sesuai, seperti kondisi batas, rentang parameter, Breakpoint, dll.
Setelah itu, ada juga baris kosong, lalu tag dokumen, yang menunjukkan beberapa informasi teknis, terutama jenis parameter panggilan, nilai dan jenis kembalian, hubungan pewarisan, metode/fungsi terkait, dll.
Mengenai penandaan dokumen, silakan lihat Bagian 4: Penandaan Dokumen untuk rinciannya.
Tag seperti <b> <code> juga dapat digunakan dalam komentar dokumen. Silakan lihat Lampiran 2 untuk detailnya.
Berikut ini adalah contoh komentar dokumentasi
/**
* Fungsi penjumlahan, mengimplementasikan penjumlahan dua bilangan
*
* Perhitungan penjumlahan sederhana, fungsi menerima dua angka a dan b, dan mengembalikan jumlah c
*
* @param ke dalam tambahan
* @param ke dalam perintah
* @mengembalikan bilangan bulat
*/
fungsi Tambah($a, $b) {
kembalikan $a+$b;
}
Dokumen yang dihasilkan adalah sebagai berikut:
Menambahkan
bilangan bulat Tambah(int $a, int $b)
[baris 45]
Fungsi penjumlahan, mengimplementasikan penjumlahan dua bilangan
Konstanta adalah penghitungan penjumlahan sederhana. Fungsi ini menerima dua angka a dan b dan mengembalikan jumlahnya c.
Parameter
• int $a - tambahkan
• int $b - perintah
5. Tag dokumen:
Cakupan penggunaan tag dokumen mengacu pada kata kunci atau tag dokumen lain yang dapat digunakan untuk memodifikasi tag tersebut.
Semua tag dokumentasi dimulai dengan @ setelah * pada setiap baris. Jika tanda @ muncul di tengah paragraf, tanda tersebut akan dianggap sebagai konten normal dan diabaikan.
@mengakses
Lingkup penggunaan: kelas, fungsi, var, definisikan, modul
Tag ini digunakan untuk menunjukkan hak akses kata kunci: privat, publik, atau dilindungi
@pengarang
Tentukan penulisnya
@hak cipta
Lingkup penggunaan: kelas, fungsi, var, definisikan, modul, penggunaan
Tentukan informasi hak cipta
@tidak digunakan lagi
Lingkup penggunaan: kelas, fungsi, var, definisikan, modul, konten, global, sertakan
Tunjukkan kata kunci yang tidak digunakan atau usang
@contoh
Tag ini digunakan untuk mengurai sebagian konten file dan menyorotnya. Phpdoc akan mencoba membaca konten file dari jalur file yang diberikan oleh tag ini.
@konst
Lingkup penggunaan: tentukan
Digunakan untuk menunjukkan konstanta yang didefinisikan dalam php
@terakhir
Lingkup penggunaan: kelas, fungsi, var
Menunjukkan bahwa kata kunci adalah kelas, metode, atau atribut final, dan dilarang diturunkan atau dimodifikasi.
@filesource
Mirip dengan contoh, hanya saja tag ini akan langsung membaca konten file php yang sedang diurai dan menampilkannya.
@global
Menunjukkan variabel global yang direferensikan dalam fungsi ini
@ingore
Digunakan untuk mengabaikan kata kunci tertentu dalam dokumen
@lisensi
Setara dengan <a> pada tag html, yang pertama adalah URL, kemudian konten yang akan ditampilkan, seperti <a href=”http://www.baidu.com”>Baidu</a>
Anda dapat menulis @license http://www.baidu.com Baidu
@link
mirip dengan lisensi
Namun Anda juga dapat menunjuk ke kata kunci apa pun dalam dokumen melalui tautan
@nama
Tentukan alias untuk kata kunci tersebut.
@kemasan
Lingkup penggunaan: tingkat halaman -> definisikan, fungsi, sertakan
Tingkat kelas->kelas, var, metode
Digunakan untuk mengelompokkan satu atau beberapa kata kunci secara logis ke dalam satu grup.
@abstrcut
Menunjukkan bahwa kelas saat ini adalah kelas abstrak
@param
Tentukan parameter suatu fungsi
@kembali
Menentukan penunjuk kembali suatu metode atau fungsi
@statis
Menunjukkan bahwa kata kuncinya statis.
@var
Tentukan jenis variabel
@versi
Tentukan informasi versi
@todo
Tunjukkan bidang-bidang yang harus ditingkatkan atau tidak dilaksanakan
@melempar
Menunjukkan pengecualian kesalahan yang mungkin ditimbulkan oleh fungsi ini. Dalam kasus ekstrim, seperti disebutkan di atas, tag dokumen biasa harus ditandai dengan @ di awal setiap baris , khususnya mencakup hal-hal berikut:
{@tautan }
Penggunaannya sama dengan @link
{@sumber }
Menampilkan konten suatu fungsi atau metode
6． Beberapa spesifikasi anotasi
a.Komentarnya harus
/**
* XXXXXXX
*/
membentuk
b. Untuk fungsi yang mereferensikan variabel global, tag glboal harus digunakan.
c. Untuk variabel, tipenya harus ditandai dengan var (int, string, bool...)
d. Fungsi harus menunjukkan parameternya dan mengembalikan nilai melalui param dan tag kembali
e. Untuk kata kunci yang muncul dua kali atau lebih, abaikan kata kunci yang berlebihan melalui ingore dan pertahankan satu saja.
f. Jika fungsi atau kelas lain dipanggil, tautan atau tag lain harus digunakan untuk menghubungkan ke bagian terkait untuk memudahkan pembacaan dokumen.
g. Gunakan komentar non-dokumentasi jika diperlukan untuk meningkatkan keterbacaan kode.
h. Jaga agar konten deskriptif tetap ringkas dan langsung pada sasaran, bila memungkinkan gunakan frasa, bukan kalimat.
i.Variabel global, variabel statis dan konstanta harus dideklarasikan dengan tag yang sesuai
7. Ringkasan
phpDocumentor adalah alat pembuatan dokumen otomatis yang sangat kuat. Ini dapat membantu kita menulis komentar standar dan menghasilkan dokumen yang mudah dipahami dan terstruktur dengan jelas, yang sangat membantu untuk peningkatan kode, pemeliharaan, penyerahan, dll.
Untuk penjelasan lebih detail tentang phpDocumentor, Anda dapat mengunjungi situs resminya
http://manual.phpdoc.org/View
8. Lampiran Lampiran 1:
Kata kunci yang dikenali oleh phpdoc:
Termasuk
Memerlukan
sertakan_sekali
memerlukan_sekali
mendefinisikan
fungsi
global
kelas
Lampiran 2
Tag yang dapat digunakan dalam dokumen
<b>
<kode>
<br>
<kdb>
<li>
<pra>
<ul>
<sampel>
<var>
Lampiran 3:
Sepotong kode php dengan komentar kanonik:
<?php
/**
* Contoh File 2, Mulai Cepat phpDocumentor
*
* File ini menunjukkan kekayaan informasi yang dapat dimasukkan ke dalamnya
* dokumentasi dalam kode melalui DocBlocks dan tag.
* @penulis Greg Beaver < [email protected] >
* @versi 1.0
* @sampel paket
*/
// contoh file #1
/**
* Dummy menyertakan nilai, untuk menunjukkan kekuatan parsing phpDocumentor
*/
include_once 'sample3.php';
/**
* Deklarasi variabel global khusus DocBlock
* @bilangan bulat global $GLOBALS['_myvar']
* @nama $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*Konstanta
*/
/**
* konstanta pertama
*/
mendefinisikan('pengujian', 6);
/**
* konstanta kedua
*/
mendefinisikan('konstanta lain', strlen('halo'));
/**
* Contoh fungsi docblock
* @global string mendokumentasikan fakta bahwa fungsi ini menggunakan $_myvar
* @staticvar integer $staticvar inilah sebenarnya yang dikembalikan
* @param string $param1 nama yang akan dideklarasikan
* @param string $param2 nilai nama
* @mengembalikan bilangan bulat
*/
function firstFunc($param1, $param2 = 'opsional') {
statis $statisvar = 7;
global $_myvar;
kembalikan $statisvar;
}
/**
* Contoh kelas pertama, ini ada dalam paket yang sama dengan
*hal-hal prosedural di awal file
* @sampel paket
* @kelas subpaket
*/
kelas kelasku {
/**
* Contoh variabel privat, ini dapat disembunyikan dengan --parseprivate
*pilihan
* @aksespribadi
* @var bilangan bulat|string
*/
var $pertamavar = 6;
/**
* @link http://www.example.com Contoh link
* @lihat kelasku()
* @menggunakan pengujian, konstanta lain
* @var susunan
*/
var $keduavar =
susunan(
'barang' =>
susunan(
6,
17,
'armadillo'
),
pengujian => konstanta lain
);
/**
* Konstruktor menyiapkan {@link $firstvar}
*/
fungsi kelas saya() {
$ini->firstvar = 7;
}
/**
* Kembalikan barang berdasarkan $paramie
* @param boolean $paramie
* @return integer|babyclass
*/
fungsi parentfunc($paramie) {
if ($paramie) {
kembali 6;
} kalau tidak {
kembalikan kelas bayi baru;
}
}
}
/**
* @paket sampel1
*/
kelas babyclass memperluas kelas saya {
/**
* Jawaban Kehidupan, Alam Semesta dan Segalanya
* @var bilangan bulat
*/
var $keduavar = 42;
/**
* Nilai konfigurasi
* @var susunan
*/
var $ketigavar;
/**
* Memanggil konstruktor induk, lalu menambah {@link $firstvar}
*/
fungsi kelas bayi() {
induk::kelasku();
$ini->firstvar++;
}
/**
* Ini selalu mengembalikan kelas saya
* @param mengabaikan $paramie
* @kembalikan kelasku
*/
fungsi parentfunc($paramie) {
kembalikan kelas saya yang baru;
}
}
?>