Bagaimana Anda mendokumentasikan proyek php?

Berkat PHP-Parser, phpDox akan selalu dapat mengurai kode PHP yang menggunakan fitur sintaks bahasa terbaru

API disediakan untuk mendaftarkan backend kustom atau diperpanjang serta pengurai anotasi DocBlock tambahan

Subsistem pengaya dari phpDox didasarkan pada plugin

Menulis plugin pengaya itu mudah dan memungkinkan phpDox memproses informasi tambahan dari alat baru dengan cepat

Subsistem generator didasarkan pada plugin, yang disebut engine

Mesin HTML default menggunakan lembar gaya XSLT yang disertakan dengan phpDox dan dapat diadaptasi atau diganti untuk menyesuaikan penyajian informasi yang diproses

Bukan rahasia lagi; . Ini seharusnya tidak terlalu mengejutkan, karena tidak hanya menulis dokumentasi merupakan tugas yang cukup membosankan, tetapi juga sulit untuk dipertahankan selama masa proyek mengingat perubahan fitur dan pemfaktoran ulang kode. Meskipun demikian, itu adalah tugas penting jika Anda dan tim Anda berniat untuk membuat kode yang dapat dipertahankan dengan baik di masa depan, bahkan melampaui peran Anda sendiri dengan berakhirnya proyek.

Untuk mengurangi beberapa kebosanan dan potensi kesalahan, alat dokumentasi otomatis dibuat. Alat ini mengurai komentar dan deklarasi kode yang ditemukan di file sumber proyek, menghasilkan dokumentasi terorganisir dalam format yang mudah digunakan. Beberapa contoh alat tersebut termasuk POD untuk Perl, JavaDoc untuk Java, dan Pydoc untuk Python. Alat-alat ini sangat populer di kalangan pengguna dari masing-masing bahasa ini karena peningkatan produktivitas yang dapat mereka bawa ke proyek besar dan kecil

Namun banyak pengembang PHP tidak menyadari bahwa alat serupa tersedia untuk PHP. Dokumentasi PHP (http. // www. phpdoc. org/) adalah utilitas kuat yang mampu menghasilkan dokumentasi dari komentar kode sumber. Mampu menghasilkan dokumentasi dalam format Docbook, HTML, PDF, dan Windows Compiled HTML Help, PHPDocumentor dapat menghilangkan kerumitan dalam membuat dan memelihara dokumentasi pengguna akhir dalam berbagai format. Pada artikel ini, saya akan memperkenalkan alat hebat ini, menunjukkan kepada Anda bagaimana menyusun komentar kode Anda dengan cara yang didukung oleh PHPDocumentor, dan menghasilkan dokumentasi yang dihasilkan dalam format yang nyaman bagi Anda

Contoh Sederhana

PHPDocumentor membuat dokumentasi dengan mem-parsing komentar yang dikenal sebagai DocBlock. DocBlock adalah komentar PHP bergaya C++ yang terlihat seperti ini

/** *   This is a DocBlock */

Untuk mendokumentasikan suatu fungsi, Anda akan menempatkan DocBlock tepat sebelum deklarasi fungsi, seperti itu

/** * Calculate circumference of circle * * The function circle() calculates the circumference of a circle,  * accepting its radius as input and returning the circumference *  * */ function circle($radius) {     $circumference = 2.0 * 3.14159 * $radius;     return $circumference;      }

DocBlock khusus ini terdiri dari dua item, yaitu deskripsi singkat dan panjang. PHPDocumentor tahu untuk memisahkan keduanya dengan mengakhiri deskripsi singkat dengan baris kosong atau periode penutup. Sementara deskripsi singkat dibatasi maksimal tiga baris, deskripsi panjang bisa sepanjang yang diperlukan

Tentu saja, fungsi bukanlah satu-satunya elemen bahasa yang dapat didokumentasikan oleh PHPDocumentor. Anda juga dapat mendokumentasikan kelas, variabel kelas, metode kelas, pernyataan definisi, variabel global, pernyataan include/include_once/require/require_once, dan halaman prosedural. Mari pertimbangkan contoh yang sedikit lebih panjang yang menunjukkan dokumentasi dari beberapa elemen bahasa yang berbeda

<?php          /**      * Include the Web page template header      */     INCLUDE "pageHeader.inc.php";     /**      * PI calculated to 5 digits      */      define("PI", 3.14159);     /**      * Calculate circumference of circle      *      * The function circle() calculates the circumference of a circle,       * accepting its radius as input and returning the circumference      *       *      */      function circle($radius)      {          $circumference = 2.0 * 3.14159 * $radius;          return $circumference;           }?>

Menghasilkan dokumentasi menghasilkan output yang ditunjukkan pada Gambar 1

Tag

Di bagian sebelumnya saya memperkenalkan dua komponen DocBlock. deskripsi pendek dan panjang. Masih ada item lain yang mungkin Anda inginkan ke dalam DocBlock, yang disebut tag. Tag adalah kata kunci yang telah ditentukan sebelumnya yang diawali dengan simbol @, dan membantu Anda membuat dokumentasi yang lebih formal dengan menentukan item informasi utama seperti penulis, nomor versi, nilai pengembalian, item yang harus dilakukan, dan hak cipta. Kembali ke fungsi circle(), saya akan memodifikasi DocBlock, menambahkan beberapa tag

/** * Calculate circumference of circle * * The function circle() calculates the circumference of a circle,  * accepting its radius as input and returning the circumference *  * @author Jason Gilmore  * @param float $radius Radius of the circle * @version 3.2 */

Regenerasi dokumentasi menghasilkan output yang ditunjukkan pada Gambar 2

Anda dapat melihat daftar lengkap tag yang didukung dengan menavigasi ke

Membagi Proyek Menjadi PaketSejauh ini saya mendasarkan contoh dari satu file. Meskipun cukup untuk membantu Anda berkenalan dengan PHPDocumentor, bahkan aplikasi sederhana seringkali terdiri dari beberapa file. PHPDocumentor mampu membuat dokumentasi untuk banyak proyek file, dilakukan dengan membagi file dan kelas ke dalam paket. Secara khusus, konstanta, fungsi, dan variabel global dikemas menggunakan DocBlock tingkat halaman, sedangkan variabel kelas dan metode dikemas menggunakan DocBock tingkat kelas. Saya akan menunjukkan cara menggunakan paket dengan cara sebelumnya. Mari tambahkan file kedua ke aplikasi, berjudul persegi. php<?php /** * This file contains the square() function. * @package squarePackage */ /** * Include the Web page template header */ INCLUDE "pageHeader.inc.php"; /** * Calculate area of a square * * The function square() calculates the area of a square, * accepting the length of each side as input and returning the area * */ function square($length) { $area = $length * $length; return $area; }?>_Perhatikan bahwa DocBlock tingkat halaman ditempatkan di awal file, dan DocBlock tingkat item pertama langsung mengikutinya. Perhatikan juga referensi ke @package bernama squarePackage. Selanjutnya saya akan memodifikasi lingkaran. php, menambahkan DocBlock tingkat halaman berikut ke atas /** * This is some file * @package circlePackage */ Regenerasi dokumentasi menghasilkan daftar isi yang terdiri dari tautan ke circlePackage dan squarePackage. Mengklik setiap tautan akan membawa Anda ke dokumen yang mirip dengan yang ditemukan pada Gambar 2

Membangun Dokumentasi

Anda dapat membuat dokumentasi proyek menggunakan skrip baris perintah phpdoc, atau antarmuka berbasis web. Saya akan menunjukkan cara menggunakan yang terakhir. Untuk memulai, unduh versi terbaru PHPDocumentor dari situs web, ekstrak ke area terlindung dari root dokumen web Anda. Saya saat ini menggunakan versi 1. 3. 0 RC3, yang merupakan versi pertama yang kompatibel dengan PHP 5. Kemudian arahkan ke index. html yang terletak di direktori PhpDocumentor. Anda akan melihat beberapa tab di bagian atas antarmuka, termasuk Pendahuluan, Konfigurasi, File, Keluaran, Opsi, Kredit, dan Tautan. Jangan ragu untuk menelusuri setiap tab untuk mengetahui tujuannya, namun untuk tujuan contoh ini Anda hanya perlu memperhatikan tab File dan Keluaran. Arahkan ke tab Files, yang digambarkan pada Gambar 3

Perhatikan bahwa Anda dapat menentukan file masukan dalam empat cara. berdasarkan file, berdasarkan direktori, file yang akan diabaikan, dan berdasarkan paket. Saya telah menambahkan direktori yang berisi lingkaran. php dan persegi. file php. Selanjutnya klik pada tab Output, digambarkan pada Gambar 4

Bidang Target digunakan untuk menentukan direktori tujuan dokumentasi. Dropdown Jenis keluaran mencantumkan berbagai templat dan jenis dokumentasi yang tersedia untuk Anda. Sepanjang tutorial ini saya telah menggunakan HTML. Pintar. bawaan. Jangan ragu untuk bereksperimen dengan format lain. Tambahkan direktori target dan tekan tombol buat yang terletak di kanan bawah jendela. Anda dapat menelusuri output yang muncul di bingkai bawah untuk meninjau tindakan PHPDocumentor. Dengan asumsi semuanya baik-baik saja, output akan diakhiri dengan “Operasi Selesai. ”. Tinjau dokumentasi Anda dengan menavigasi ke folder target

Kesimpulan

Dalam artikel ini saya hanya memperkenalkan segelintir kemampuan PHPDocumentor, meskipun mudah-mudahan artikel singkat ini menjelaskan bahwa ini adalah salah satu alat yang Anda tidak bisa hidup tanpanya. Seperti biasa, saya menyambut pertanyaan dan komentar. Silakan e-mail saya di wj AT wjgilmore. com

tentang Penulis

W. Jason Gilmore (http. // www. wjgilmore. com/) adalah Direktur Editorial Sumber Terbuka untuk Apress (http. // www. apres. com/). Dia adalah penulis Permulaan PHP 5 dan MySQL. Pemula hingga Profesional (Apress, 2004. 748pp. ). Karyanya telah ditampilkan dalam banyak publikasi terkemuka industri komputasi, termasuk Majalah Linux, O'Reillynet, Devshed, Zend. com, dan Webreview. Jason juga penulis Pengantar Programmer untuk PHP 4. 0 (453 hal. , Apres). Bersama rekannya Jon Shoberg, dia adalah salah satu penulis “Out in the Open,” sebuah kolom bulanan yang diterbitkan dalam majalah Linux

Bagaimana cara mendokumentasikan proyek saya?

Apa situs yang memberikan semua dokumentasi tentang PHP?

Bagaimana Anda mendokumentasikan aplikasi?

Bagaimana cara melakukan dokumentasi kode?