Memakai phpDocumentor 2 Di Zend Studio 10.5


Salah satu cara untuk mempermudah komunikasi antar developer adalah dengan memberikan dokumentasi di dalam kode program. Java memiliki sebuah standar dokumentasi dalam bentuk komentar yang disebut sebagai JavaDoc. PHP sebagai bahasa dinamis tentunya lebih membutuhkan sebuah mekanisme dokumentasi (terutama dari pengembang framework/library). IDE seperti Zend Studio, NetBeans dan Aptana Studio dapat memanfaatkan dokumentasi untuk ditampilkan sebagai content assist. Sayangnya, PHP tidak dilengkapi dengan mekanisme dokumentasi secara bawaan. Sebagai gantinya, terdapat adaptasi dari JavaDoc yang disebut sebagai PHPDoc. Spesifikasi formal untuk PHPDoc berupa PSR-5: PHPDoc dapat dibaca di https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md.

phpDocumentor 2 adalah tool yang dapat dipakai untuk menghasilkan dokumentasi yang ada di kode program dalam bentuk HTML (mirip dengan memakai perintah javadoc di Java). Pengembangan tool ini sangat aktif dimana rilis terakhirnya adalah versi 2.1.0 pada tanggal 14 Oktober 2013. Saya akan mencoba memakai phpDocumentor 2 di IDE Zend Studio 10.5.

Sebelum dapat mulai menggunakan phpDocumentor di Zend Studio, saya perlu men-install pluginnya terlebih dahulu. Untuk itu, saya memilih menu Help, Welcome. Pada halaman yang muncul, saya memilih PHP Tools, lalu memberi tanda centang pada PHPDocumentor seperti yang terlihat pada gambar berikut ini:

Men-install plugin PHP Documentor

Men-install plugin PHP Documentor

Setelah itu saya men-klik tombol Apply changes. Setelah proses download dan instalasi selesai, saya memilih Yes untuk me-restart Zend Studio. Sekarang, saya siap untuk memakai PHPDocumentor

Saya akan mulai dengan membuat sebuah proyek baru di Zend Studio dengan memilih menu File, New, dan Local PHP Project. Pada dialog yang muncul, saya mengisi informasi seperti pada gambar berikut ini:

Membuat proyek baru di Zend Studio 10.5

Membuat proyek baru di Zend Studio 10.5

Setelah itu, saya men-klik tombol Next. Saya kemudian memilih Launch CLI Application dan men-klik tombol Finish. Zend Studio akan membuat sebuah proyek baru dengan nama latihan.

Anggap saja saya akan mendefinisikan domain class pada proyek ini. Saya men-klik kanan nama proyek, memilih menu New, Class untuk membuat sebuah class baru. Saya mengisi dialog yan muncul seperti pada gambar berikut ini:

Membuat class baru

Membuat class baru

Setelah itu, saya men-klik tombol Finish. Saya kemudian membuat kode program seperti berikut ini:

<?php
/**
 * Definisi untuk class `Pesanan`
 * 
 * @author TheSolidSnake
 *
 */
namespace domain;

/**
 *  Mewakili pesanan yang dilakukan oleh pelanggan
 *  
 *  Class Pesanan mewakili sebuah pemesanan yang dilakukan oleh pelanggan. Sebuah `Pesanan` dapat terdiri atas
 *  satu atau lebih `Item`.  Sebuah `Pesanan` **WAJIB** memiliki minimal sebuah `Item`.
 *   
 *  `Pesanan` dapat memiliki beberapa tahap workflow, seperti pesanan diterima, kemudian diproses, dan diambil.  
 *  Class `Event` mewakili informasi untuk workflow tersebut seperti tanggal dan user yang bertanggung jawab.
 *  
 *  @author TheSolidSnake
 *  @see \domain\Item
 *  @see \domain\Event        
 */
class Pesanan {

    /** 
     * Nomor pesanan yang dihasilkan secara otomatis berurut seperti WO/2013/ABCD.
     * 
     * @var integer 
     * */
    public $nomor; 

    /** 
     * Array yang berisi `Item` untuk pemesanan ini.
     * 
     * @var \domain\Item[]   
     * */
    public $items;

    /** 
     * Array yang berisi `Event` untuk pemesanan ini.
     * 
     * @var \domain\Event[] 
     * */
    public $event;

    /**
     * Menambah item baru untuk pemesanan ini.
     * 
     * @param \domain\Item $item adalah sebuah `Item` yang akan ditambahkan.  Nilai ini tidak boleh kosong.
     * @param integer $harga adalah harga yang harus ditagihkan untuk `Item` yang dipilih.  Bila nilai ini tidak
     * diberikan, maka harga akan diambil dari daftar eceran tertinggi untuk `Item` yang dipilih. 
     */
    public function tambahItem($item, $harga = NULL) {

    }

    /**
     * Menambah event baru untuk pemesanan ini.
     * 
     * @param \domain\Event $event adalah `Event` yang akan ditambahkan untuk pemesanan ini.  Tanggal `Event` secara
     * otomatis akan di-isi dengan tanggal hari ini, dan user yang bertanggung jawab adalah user yang sedang login
     * pada saat method ini dikerjakan.
     */
    public function tambahEvent($event) {

    }

}
?>

PHP Documentor 2 membolehkan penggunaan markdown di PHPDoc (tidak seperti JavaDoc yang terbatas pada HTML). Untuk menghasilkan dokumentasi dalam bentuk HTML, saya men-klik kanan nama proyek, kemudian memilih menu Generate PHPDoc. Pada dialog yang muncul, saya menentukan lokasi dimana dokumentasi HTML akan dihasilkan dan men-klik tombol Finish. PHP Documentor setelah selesai bekerja akan menghasilkan dokumentasi HTML yang tampilannya seperti berikut ini:

Hasil dokumentasi dalam bentuk HTML

Hasil dokumentasi dalam bentuk HTML

Untuk mengganti profile yang dipakai PHP Documentor (misalnya untuk mengubah template yang dipakai), saya dapat memilih menu Window, Preferences, PHP, PHPDocumentor Profile. Akan muncul sebuah dialog dimana saya dapat mengubah profile untuk PHP Documentor.

PHP Documentor 2.1 tampaknya tidak dapat menghasilkan dokumentasi untuk tag @see dengan baik. Disisi lain, Zend Studio dapat memanfaatkan PHPDoc untuk menampilkan informasi bagi programmer, menampilkan @see sebagai link, namun Zend Studio tidak mengerti syntax Markdown, sehingga content assist akan terlihat pada gambar berikut ini:

Tampilan content assist di Zend Studio 10.5

Tampilan content assist di Zend Studio 10.5

Tampilan content assist di Zend Studio 10.5

Tampilan content assist di Zend Studio 10.5

Kesimpulannya adalah metode dokumentasi pada PHP masih belum universial. Sepertinya masih dibutuhkan waktu agar pembuat IDE dan pembuat documentation generator setuju pada sebuah ketentuan PHPDoc yang seragam.

Perihal Solid Snake
I'm nothing...

Apa komentar Anda?

Please log in using one of these methods to post your comment:

Logo WordPress.com

You are commenting using your WordPress.com account. Logout / Ubah )

Gambar Twitter

You are commenting using your Twitter account. Logout / Ubah )

Foto Facebook

You are commenting using your Facebook account. Logout / Ubah )

Foto Google+

You are commenting using your Google+ account. Logout / Ubah )

Connecting to %s

%d blogger menyukai ini: