ngoding

Jika kamu pernah mencoba untuk membaca kode program dari orang lain, kamu pasti mengetahui bahwa pekerjaan itu sangat menakutkan. Kode program yang bercampur baur ditambah nama variabel yang aneh-aneh membuat kepalamu serasa berputar-putar. Apakah fungsi ini mengembalikan string atau array? Apakah variabel ini menyimpan integer atau object? Setelah berjam-jam mengikuti alur kode dan mencoba memahami apa yang setiap bit lakukan, tidak jarang kemudian menyerah dan hanya menulis ulang semuanya dari awal – tugas yang buang terlalu banyak waktu berharga Anda.

Phpdoc, singkatan dari phpDocumentor, adalah alat yang ampuh yang memungkinkan Anda untuk dengan mudah mendokumentasikan kode Anda melalui komentar yang diformat khusus. Dokumentasi akan tersedia tidak hanya dalam kode sumber, tetapi juga dalam dokumentasi profesional diekstraksi baik menggunakan web atau antarmuka baris perintah. Hasilnya bisa dalam berbagai format seperti HTML, PDF, dan CHM. Selain itu, banyak IDE yang menyediakan code-completion dapat mengurai komentar phpdoc dan menyediakan fitur yang berguna seperti tipe-hinting. Dengan menggunakan phpdoc, Anda dapat membuatnya mudah bagi orang lain (dan diri sendiri) untuk memahami kode Anda – minggu, bulan, dan bahkan bertahun-tahun setelah Anda menulisnya.

Cara termudah untuk menginstal phpdoc adalah dengan PEAR. Tentu saja, sebelum Anda dapat melakukannya Anda harus memiliki PEAR diinstal. Jika Anda tidak, ikuti petunjuk di pear.php.net/manual/en/installation.php.

Dalam artikel ini saya akan menunjukkan kepada Anda bagaimana menggunakan phpdoc untuk menghasilkan dokumentasi cantik dan user-friendly dari awal sampai akhir.

DocBlocks

DocBlock adalah gaya komentar multi-line C digunakan untuk mendokumentasikan suatu blok kode. Ini dimulai dengan / ** dan memiliki tanda bintang pada awal setiap baris. Berikut ini contohnya:

<?php
/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to
 * total. Returns total.
 *
 * This function can also be implemented using array_reduce();
 *
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

DocBlocks terdiri dari tiga bagian: deskripsi singkat, deskripsi panjang, dan tag. Semua tiga bagian itu adalah opsional.

Deskripsi singkat adalah deskripsi singkat diakhiri oleh salah satu baris baru atau period. Rutinitas parsing phpdoc yang pintar, hanya akan mengakhiri deskripsi singkat jika periode ini di akhir kalimat.

Deskripsi panjang adalah di mana sebagian besar dokumentasi berjalan, bisa multi-line dan sebanyak yang Anda inginkan.

Kedua deskripsi panjang dan pendek dapat mengandung elemen HTML tertentu untuk format. Tag HTML yang tidak didukung akan ditampilkan sebagai teks biasa. Phpdoc dapat menghasilkan dokumentasi dalam berbagai format, sehingga tag HTML tidak selalu diberikan sebagaimana dalam sebuah file HTML, format yang sebenarnya tergantung pada format file yang dihasilkan. Jika Anda perlu untuk menampilkan tag HTML sebagai teks, gunakan tanda kurung ganda. Sebagai contoh:

<?php
/**
 * Here an example of the italics tag: <<i>>Hello, world!<<i>>
 */

Bagian tag DocBlock mengandung sejumlah tag khusus dilambangkan dengan simbol @. Tag yang digunakan untuk menentukan informasi tambahan, seperti parameter yang diharapkan dan jenis mereka. Kebanyakan tag harus berada pada jalur sendiri, dengan pengecualian dari tag tertentu yang mungkin inline. Tag Inline dikelilingi dengan kurung kurawal dan mungkin di kedua deskripsi panjang dan pendek. Untuk daftar lengkap tag, periksa dokumentasi phpdoc relevan.

Jika Anda perlu untuk memulai baris dengan simbol @ tetapi Anda tidak ingin ditafsirkan sebagai tag, Anda dapat menambahkan garis miring terbalik.

Phpdoc otomatis akan mengenali daftar tekstual dalam deskripsi panjang dan pendek dan itu akan menguraikannya. Namun, tidak akan mengurai daftar bersarang dengan benar. Jika Anda ingin menggunakan daftar bersarang, gunakan tag HTML. Berikut adalah contoh untuk menggambarkan apa yang saya maksud:

<?php
/**
 * Example of using lists
 *
 * PhpDoc will parse this list correctly:
 * - Item #1
 * - Item #2
 * - Item #3
 *
 * But not this list:
 * - Item 1
 *   - Item 1.1
 *   - Item 1.2
 * - Item 2
 *
 * Use this instead for a nested list:
 * <ul>
 *   <li>Item 1</li>
 *   <ul>
 *     <li>Item 1.1</li>
 *     <li>Item 1.2</li>
 *   </ul>
 *   <li>Item 2</li>
 * </ul>
 */

Packages

Paket phpdoc digunakan untuk elemen kode kelompok terkait dalam dokumentasi yang dihasilkan. Anda dapat menentukan paket untuk file dan kelas dan kode terdokumentasi yang dikandungnya akan mewarisi paket dari mereka. Untuk menentukan paket, mengatur tag @package dalam file-level atau tingkat kelas DocBlock  (file-level dan kelas-tingkat DocBlocks akan dibahas lebih lanjut adalah bagian berikut). Sebuah nama paket dapat berisi huruf, angka, tanda hubung, garis bawah, dan tanda kurung siku (“[” dan “]”).

Berikut adalah contoh mendefinisikan sebuah paket file:

<?php
/**
 * This is a file-level DocBlock
 *
 * @package Some_Package
 */

Jika Anda memiliki beberapa tingkat paket dan sub-paket, Anda dapat menentukan paket sub-sub-paket dengan tag @. Berikut adalah contoh:

<pre><?php
/**
 * This is a file-level DocBlock
 *
 * @package Some_Package
 */</pre>

Jika sebuah file atau kelas tidak menentukan paket itu akan diatur untuk paket standar, “default”. Anda dapat menentukan paket yang berbeda yang akan digunakan secara default saat membuat dokumentasi melalui opsi baris perintah -dn.

What Can I Document?

Tidak semua elemen kode dapat didokumentasikan dengan DocBlocks. Berikut adalah daftar elemen kode yang dapat didokumentasikan:

  • Files
  • Classes
  • Functions and methods
  • Class properties
  • Global variables
  • include()/require()
  • define()

Semua elemen dapat menggunakan tag umum tertentu, tetapi masing-masing memiliki tag yang spesifik untuk elemen. Aku akan pergi ke beberapa elemen dan tag yang biasanya digunakan untuk mendokumentasikan mereka.

Files

DocBlocks tingkat-File digunakan untuk mendokumentasikan isi dari file. Hal ini sangat dianjurkan untuk menyertakan DocBlock file-level di setiap file yang Anda dokumen, dan pada kenyataannya phpdoc akan menampilkan peringatan jika ada yang tidak ditemukan saat membuat dokumentasi.

Kebanyakan elemen didokumentasikan dengan menempatkan DocBlock sebelum elemen, namun file mendapatkan pengecualian (karena Anda tidak bisa menulis apa pun sebelum file). DocBlocks tingkat-File ditempatkan pada baris pertama dari file.

Sebuah DocBlock file-level biasanya berisi tag @package, @subpackage, @license, and @author. tag @package dan @subpackage telah dibahas sebelumnya. Tag @license digunakan untuk menentukan URL untuk lisensi eksternal yang mencakup kode Anda. Tag harus berisi URL untuk lisensi dan judul (opsional). Tag @author digunakan untuk menentukan penulis file. Ini harus berisi nama penulis dan opsional alamat email dalam kurung sudut.

Tidak seperti sebagian besar elemen, sebuah DocBlock file-level harus berisi tag @package agar dapat diurai dengan benar.

Berikut ini adalah contoh lengkap dari DocBlock file-level:

<?php
/**
 * This file contains common functions used throughout the application.
 *
 * @package    MyProject
 * @subpackage Common
 * @license    http://opensource.org/licenses/gpl-license.php  GNU Public License
 * @author     Moshe Teutsch <moteutsch@gmail.com>
 */

Classes

Sebuah DocBlock tingkat kelas ditempatkan sebelum definisi kelas dan harus menjelaskan makna dari kelas. Seperti file-level DocBlocks, DocBlocks tingkat kelas biasanya mengandung paket tag @package, @subpackage, dan @author.. Berikut adalah contoh:


<?php
/**
 * An example class
 *
 * The class is empty for the sake of this example.
 *
 * @package    MyProject
 * @subpackage Common
 * @author     Moshe Teutsch <moteutsch@gmail.com>
 */
class Example {
}

Functions and methods

Functions and methods are documented identically in PhpDoc. (For those who may not be familiar with the terminology, a method is just a function within a class.) Functions and methods usually contain the @param and @return tags in their DocBlocks. The @param tag is used to document the expected type of a parameter. It contains three sections: the parameter, the data type, and an optional description. The @return tag is used to document the return type. It contains two sections: the data type and an optional description. In both tags, the data type can be either a valid PHP data type, a class name, or “mixed”. It can also contain multiple options separated by a pipe.

Fungsi dan metode didokumentasikan identik di phpdoc. (Bagi mereka yang mungkin tidak akrab dengan terminologi, metode hanya fungsi dalam kelas.) Fungsi dan metode biasanya mengandung tag @param dan @return dalam DocBlocks mereka. Tag @param digunakan untuk mendokumentasikan tipe yang diharapkan dari parameter. Ini berisi tiga bagian: parameter, tipe data, dan deskripsi opsional. Tag @return digunakan untuk mendokumentasikan jenis kembalian. Ini berisi dua bagian: tipe data dan deskripsi opsional. Dalam kedua tag, tipe data dapat berupa tipe data PHP yang valid, nama kelas, atau “gabungan keduanya”. Hal ini juga dapat berisi beberapa pilihan dipisahkan oleh pipa “|”.


<?php
/**
 * Finds and returns user by ID or username
 *
 * @param int|string $user Either an ID or a username
 * @param PDO $pdo A valid PDO object
 * @return User Returns User object or null if not found
 */
function getUser($user, PDO $pdo)
{
    // ...
    if ($isFound) {
        return new User(...);
    }
    return null;
}

Generating Documentation

Once you’ve documented your PHP code, you’ll want to generate user-friendly documentation from it. To do so, run the PhpDoc command-line tool.

Setelah Anda didokumentasikan kode PHP Anda, Anda akan ingin untuk menghasilkan dokumentasi yang user-friendly darinya. Untuk melakukannya, jalankan tool baris perintah phpdoc.

phpgeek@localhost:~$ phpdoc -d /path/to/files/ -t /path/to/docs/ -ti 'Documentation Title' -dn 'Default Package' -o HTML:frames:default

Opsi -d menetapkan daftar dipisahkan koma dari direktori yang berisi file dokumen, dan -t path/direktori ke dokumen yang dihasilkan. -ti digunakan untuk menentukan judul proyek, dan -dn untuk menetapkan nama paket default. Akhirnya, -o menentukan format dokumentasi. Phpdoc memiliki berbagai pilihan format untuk dipilih. Sebuah daftar lengkap tersedia di situs phpdoc.

Anda dapat mengetahui lebih lanjut tentang alat baris perintah dengan menjalankan perintah bantuan sebagai berikut:

phpgeek@localhost:~$ phpdoc -h

Setelah Anda menjalankan perintah, jalur dokumentasi yang Anda tentukan harus berisi dokumentasi yang dihasilkan.

Bagi Anda yang tidak nyaman menggunakan antarmuka baris perintah, phpdoc juga memiliki antarmuka web yang tersedia. Itu adalah di luar lingkup artikel ini untuk membahasnya panjang lebar, tetapi Anda dapat membaca lebih lanjut tentang hal itu di situs resmi phpdoc itu, phpdoc.org.

Summary

Dalam artikel ini saya memberi Anda pandangan pertama mengenai phpdoc dan banyak fitur canggih. Saya telah menjelaskan tujuan DocBlocks dan komponen mereka, saya telah menunjukkan Anda bagaimana untuk mengatur dokumentasi Anda menggunakan paket, saya telah menjelaskan unsur-unsur kode dapat didokumentasikan dan beberapa contoh umum untuk melakukannya, akhirnya, saya telah menunjukkan Anda bagaimana untuk menghasilkan dokumentasi dari kode sumber Anda. Saya sangat menyarankan Anda mulai menggunakan phpdoc dalam proyek Anda sendiri, jika bahkan hanya untuk mendokumentasikan bagian yang paling penting. Hal ini sangat lurus ke depan dan akan menyelamatkan Anda dan rekan kerja Anda berjam-jam menggigit kuku dan menarik-narik rambut.

diterjemahkan bebas dari http://phpmaster.com/introduction-to-phpdoc/. semoga bisa membantu rekan-rekan yang kesulitan dalam bahasa inggris mereka.

Advertisements

About phpgeek programmer

pemimpi yang berharap menjadi the best programmer di zamannya

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s