Skip to content

Eylül 21, 2010

2

PHP Documentor Kullanımı ve Tag Listesi

PHP Doc

Merhaba arkadaşlar, bu yazımızda Java Doc baz alınarak PHP ‘ye adapte edilen bir kod belgelendirme/yorumlama standardını olan PHP Doc ‘u incelemeye çalışacağız. Hepimiz kod yazıyoruz ve yazdıktan sonra güncelleme/inceleme gereği olmadığı sürece yada o sınıf/metodu uzunca süre kullanmadığımız zaman kodu tekrar görmüyoruz.

Neden kullanmalıyız?

Başkasının yazdığı veya yukarıdaki şartları taşıyan kodu incelemek/kullanmak/anlamak için ne kadar çaba sarf ettiğimizi biliyoruz. Bu süreyi minimuma indirmek ve yazdığımız her şeyin indeksini oluşturabilmek için (kaç tane sınıf var, metodları neler, hangi tipte kaç parametrelere alırlar, ne tipte bir nesne döndürürler, kim yazdı, versiyonu nedir gibi) bu kullanışlı aracı kodlarınıza ve CV nize güzel bir yıldız olarak ekleyebilirsiniz.

Tag Listesi

Şimdilik en yaygın PHP Doc taglarını inceleyip yazıyı bitiyoruz sonrasında kullanım örnekleri ve IDE entegrasyonlarına göz atacağız.

  • @access (erişim metodu)
  • @author (yazar bilgisi)
  • @copyright (Telif hakkı bilgisi)
  • @deprecated (Terk edilmiş metod/sınıf/nesne)
  • @example (Kullanım örneği)
  • @link (Döküman içerisinde link gösterir)
  • @see (Döküman içerisinde bir nesneye link verir. Bakınız olarak kullanılır)
  • @since (x versiyonundan buyana kullanılıyor şeklinde kullanılır)
  • @version (versiyon bilgisi)
  • @param (metod/fonksiyon parametresi)
  • @return(metod/fonksiyon dönüş tipi)
  • @assert (PHP Doc standartlarında görünmesede bir başka Java  ‘dan gelen özellik olan JUnit ‘in PHP hali PHP Unit Test için case ekler )

Örnek Kullanım (sayfa yorumu)

/**
* Bu dosya bazı genel fonksiyonlar içerir.
*
* PHP yorumundan farkı iki tane yıldız ile başlamasıdır.
* @author Mustafa KIRIMLI <info@mustafakirimli.com>
* @version 1.0
*/

Örnek Kullanım (fonksiyon yorumu)

/**
* Verilen sayıları toplayan bir fonksiyondur.
* @param integer $sayi1 toplanacak ilk sayı
* @param integer $sayi2 toplanacak ikinci sayı
* @return integer toplama işleminin sonucu
*/
function Topla($sayi1, $sayi2)
{
    return (int) $sayi1 + $sayi2;
}

Sonuç

Kodlara bu yorumları eklediğimizde ne işe yarayacak diyorsanız bunu başka bir yazıda anlatacağız. PHP Doc. oluşturucuları sayesinde sayfaların, sınıfların, metodların ve değişkenlerin indeksini çıkartıp proje dosyasınızda bulundurabilirsiniz. Ayrıca kullandığınız editor yada IDE destekliyorsa (bir çoğu bunu yapıyor, Netbeans ile nasıl kullanıldığını göreceğiz) kod yazarken size yardımcı olacaktır.

Toplam 2 Yorum Yorum Yaz
  1. engin
    Ara 1 2011

    hay ALLAH razı olsun. kaç gündür bunları arıyordum. bu tarz bir döküman bulamamıştım. bunun devamını da bekliyoruz. Ellerinize sağlık.

    Cevapla

Trackbacks & Pingbacks

  1. PHP İle SOAP Web Servisi Oluşturmak (SOAP Server) | Web Projeleri Optimizasyonu ve Benchmark

Sizin fikriniz nedir? Lütfen aşağıdaki formu kullanarak yorum yapın.

(gerekli)
(gerekli)