kurtkuzu
10-11-2007, 23:31 PM
phpDoc kullanarak otomatik belgeler hazırlayabilirsiniz
Başarılı bir yazılım için belgelendirme kalitesi, kod kalitesinden daha önemlidir.
Açık kaynak veya özel projelerinizde gerekli belgelerin hazırlanması "kodların tekrar kullanımı", "kodlama standartları", "yazım disiplini" ve "ekip çalışması" gibi konularda başarı için anahtar rol oynayacaktır.
Belgelerin kimin için hazırlandığına karar verilmesi
Yazdığınız belgelerin kimler tarafından okunacağına karar verilmesi kullanıcıların ihtiyaçları açısından farklılık taşır.
Son kullanıcı diye adlandırdığımız programı asıl kullanacak kişiler için sadece genel kavramlar, giriş seviyesinde bilgiler (teknik ayrıntılardan kaçının), programın kullanıma verilen örnekler ve örnek olaylar (örnek: kullanıcı nasıl kayıt olur, nasıl soru çözer...) önemlidir.
Ancak programcılar için aşağıdaki maddeler önemlidir.
1) Programın öğelerinin birbirlerini nasıl etkileği
2) Hangi işlev, değişken, sınıf diğer hangi sınıfı, değişkeni veya işlevi kullandığı.
3) Verilen komutlar hangi durumlarda çalıştığı.
4) Yazılan kod başka işlevler için nasıl kullanıldığı. Örneğin iki sayının ortalamasını veren bir işlev, öğrenci notlarının ortalamasının hesaplanmasında nasıl kullanılabilir?
önemlidir.
Örnek:
<?php
//... önceki komutlar
if($ort<50)
{
// yapılacak eylemler
}
?>
yerine
<?php
//... önceki komutlar
/**
* Öğrencinin not ortalaması 50 nin altında olduğunda şu
* işlemler yapılır...
*/
if($ort<50) {
// yapılacak eylemler
}
?>
phpDoc Kurulumu
phpDoc pear sınıfı olarak kurulabileceği gibi http://www.phpdoc.org/ sitesinden paket olarak indirilip http protokolu ile php dosyalarınızı çalıştırdığınız "DOCUMENT_ROOT" altında istediğiniz her hangi bir dizine indirdiğiniz tar.gz dosyasını açmak suretiyle de çok basit bir şekilde kurabilirsiniz. Html olarak çıktı almayı düşünüyorsanız program smarty sınıfını kullandığı için sunucunuzun smarty/templates_c dizinine yazma izninin olmasını sağlamalısınız.
Kurulum için php-cli (php için kabuk desteği) olması gereklidir ayrıntılı gereksinimleri phpdoc.org sitesinden öğrenebilirsiniz.
Sonra sadece tarayıcınıza http://localhost/phpDoc/ yazmanız yeterlidir.
Asıl olarak phpDoc komut satırında çalışacak şekilde tasarlanmıştır. Ancak yapılan arayüz ayar dosyalarını yazıp üst düzey işlevlere imkan sağlayacak kadar esnek ve web üzerinde çalıştığı için bir kaç fare tıklamasıyla hiç bilmeyen birisinin de yazdığı kodlardan belge üretmesine imkan sağlayacak kadar kolay...
Sadece yapmanız gereken hedef dizin olarak belirlediğiniz yerin dosya sahipliklerini 0777 olarak (apache ye yazım izni vermelisiniz) belirlemek..
Örnek dosya
<?php
/**
* Sayfa seviyesinde açıklama bölümü
*
* php etiketinden sonraki ilk yorum bölümü sayfa
* seviyesinde açıklama bölümü olarak nitelendirilir.
* phpDoc ile bu programı yorumlattığımızda bu satırlar
* dosya için yardım satırları olarak görüntülenecektir.
*
* @author Sinan Yalçınkaya < sinan@sinavbankasi.com >
* @package sohbet
* @copyright www.sinavbankasi.com
*/
/**
* Örnek bir nesne için açıklama
*
* Burada nesne hakkında genel bilgiler yazılacak. Ben bu
* nesneyi sohbet isminde bir nesneden türettim dolayısıyla
* belge üretiminde bu sınıfın ilişkili olduğu diğer sınıfları
* "see" etiketiyle belirterek bu açıklama sayfasından sohbet
* sınıfına bağlantı eklenmesini sağlıyorum. "see" etiketi
* etkin olarak kullanılması gereken bir etikettir.
*
* @see sohbet
*/
class sohbet_yonetim extends sohbet
{
/**
* Son X günlük mesajların listesi
*
* Konuya göre gruplandırılmış şekilde açık ve önemli (1 ve 2) mesajların listesini
* bulunduran değişkendir.
*
* Kapalı ve sistem mesajı olarak listelenmiş mesajlar için son 1 günlük kayıtları
* listeler.
*
*
* $liste[0..n]
* 'konu_no'=>integer,
* 'kul_adi'=>string, // Mesajı gönderen kullanıcının adı
* 'son_msj'=>string, // Bu konuda gönderilen son mesaj
* 'son_msj_kuladi'=>string,// Mesaja en son cevap veren kullanıcı
* 'son_msj_tarih'=>date, // Gönderilen son mesajın tarihi
* 'yeni_msj_say'=>integer, // Yeni mesj, yönetici için
* 'son_okuma'=>date, // Yöneticinin o mesajı son okuma tarihi
* 'kul_son_okuma'=>date, // Kullanıcının o mesajı son okuma tarihi
* 'kul_online'=>boolean, // Eğer kullanıcı o mesajı son 3 dak içinde okumuşsa doğru
* 'durum'=>integer, // Mesajın nasıl işaretlendiği (açık, kapalı, önemli..)
*
*
* @access public
* @var array
*/
var $liste = array();
/**
* Mesajların Listesi
*
* Burada çeşitli işlemler yapılarak $liste
* oluşturulmaya çalışılacak.
*
* @return array
* @access public
* @see $liste
*/
function liste()
{
// buraya kodlar gelecek
}
}
?>
Genel Kullanım
Linux için:
phpdoc -t hedefdizin -o HTML:default:default -d cevrilecekdizin
Windows İçin:
C:\>php.exe "C:\phpdoc\yeri\phpdoc" -t hedefdizin -o HTML:default:default -d cevrilecekdizin
hedefdizin: Hazırlanan belgelerin kaydedileceği dizin
cevrilecekdizin: İçerisindeki php dosyalarının okunarak onlardan belge üretilecek olan dizin
Aynı zamanda paketin içerisinden yer alan makedoc.sh dosyasını isteğinize göre değiştirip belge hazırlamayı kolaylaştırabilirsiniz.
phpDocumantor Etiketleri (komutları)
PhpDoc için açıklama yazarken kullanacağımız komutları burada anlatmaya çalışacağım.
Dosya başlığı komutları
/**
* Dosya için genel bir başlık
*
* Hazırlanan dosya için genel açıklama satırları
*
* @author Sinan Yalçınkaya < sinan@sinavbankasi.com >
* @package sohbet
* @copyright www.sinavbankasi.com
* @version 1.0
*/
@author: Programı yazan, eğer birden fazla ise ilk yazardan sonra virgül koyarak diğer yazarlar eklenir
@package: Dosyanın hangi paket altında yer aldığı burada belirtilir
@copyright: Programın telif hakları ile ilgili not bölümü
@version: Programın sürüm bilgileri bu komut ile belirtilir
@access Etiketi
Bu etiket açıklama bloklarının hangilerinin belgede yer alıp almayacağını belirtmekte kullanılır.
Örnek:
/**
* Genel açıklama satırları için erişim bilgisi kullanımı
*
* Varsayılan olarak @access etiketinin değeri "public" yani
* herkese açıktır.
*
* @access public
*/
function acikIslev(){
// komut satırları
}
/**
* "private" (özel) denilerek bu satırların ve altta yer alan
* nesne, değişken, işlev vb.. öğelerin hazırlanan belgede
* gizlenmesi sağlanır.
*
* @access private
*/
function gizliIslev(){
//komut satırları
}
/**
* "protected" (korumalı) denilerek sadece öğeye ait açıklama
* satırlarının (bu okuduğunuz satırların) gizlenmesi
* ancak ilgili öğeye hazırlanan belgede atıfta bulunulması
* sağlanır.
*
* @access protected
*/
function belgedeYerAlacakIslev(){
//komut satırları
}
Başarılı bir yazılım için belgelendirme kalitesi, kod kalitesinden daha önemlidir.
Açık kaynak veya özel projelerinizde gerekli belgelerin hazırlanması "kodların tekrar kullanımı", "kodlama standartları", "yazım disiplini" ve "ekip çalışması" gibi konularda başarı için anahtar rol oynayacaktır.
Belgelerin kimin için hazırlandığına karar verilmesi
Yazdığınız belgelerin kimler tarafından okunacağına karar verilmesi kullanıcıların ihtiyaçları açısından farklılık taşır.
Son kullanıcı diye adlandırdığımız programı asıl kullanacak kişiler için sadece genel kavramlar, giriş seviyesinde bilgiler (teknik ayrıntılardan kaçının), programın kullanıma verilen örnekler ve örnek olaylar (örnek: kullanıcı nasıl kayıt olur, nasıl soru çözer...) önemlidir.
Ancak programcılar için aşağıdaki maddeler önemlidir.
1) Programın öğelerinin birbirlerini nasıl etkileği
2) Hangi işlev, değişken, sınıf diğer hangi sınıfı, değişkeni veya işlevi kullandığı.
3) Verilen komutlar hangi durumlarda çalıştığı.
4) Yazılan kod başka işlevler için nasıl kullanıldığı. Örneğin iki sayının ortalamasını veren bir işlev, öğrenci notlarının ortalamasının hesaplanmasında nasıl kullanılabilir?
önemlidir.
Örnek:
<?php
//... önceki komutlar
if($ort<50)
{
// yapılacak eylemler
}
?>
yerine
<?php
//... önceki komutlar
/**
* Öğrencinin not ortalaması 50 nin altında olduğunda şu
* işlemler yapılır...
*/
if($ort<50) {
// yapılacak eylemler
}
?>
phpDoc Kurulumu
phpDoc pear sınıfı olarak kurulabileceği gibi http://www.phpdoc.org/ sitesinden paket olarak indirilip http protokolu ile php dosyalarınızı çalıştırdığınız "DOCUMENT_ROOT" altında istediğiniz her hangi bir dizine indirdiğiniz tar.gz dosyasını açmak suretiyle de çok basit bir şekilde kurabilirsiniz. Html olarak çıktı almayı düşünüyorsanız program smarty sınıfını kullandığı için sunucunuzun smarty/templates_c dizinine yazma izninin olmasını sağlamalısınız.
Kurulum için php-cli (php için kabuk desteği) olması gereklidir ayrıntılı gereksinimleri phpdoc.org sitesinden öğrenebilirsiniz.
Sonra sadece tarayıcınıza http://localhost/phpDoc/ yazmanız yeterlidir.
Asıl olarak phpDoc komut satırında çalışacak şekilde tasarlanmıştır. Ancak yapılan arayüz ayar dosyalarını yazıp üst düzey işlevlere imkan sağlayacak kadar esnek ve web üzerinde çalıştığı için bir kaç fare tıklamasıyla hiç bilmeyen birisinin de yazdığı kodlardan belge üretmesine imkan sağlayacak kadar kolay...
Sadece yapmanız gereken hedef dizin olarak belirlediğiniz yerin dosya sahipliklerini 0777 olarak (apache ye yazım izni vermelisiniz) belirlemek..
Örnek dosya
<?php
/**
* Sayfa seviyesinde açıklama bölümü
*
* php etiketinden sonraki ilk yorum bölümü sayfa
* seviyesinde açıklama bölümü olarak nitelendirilir.
* phpDoc ile bu programı yorumlattığımızda bu satırlar
* dosya için yardım satırları olarak görüntülenecektir.
*
* @author Sinan Yalçınkaya < sinan@sinavbankasi.com >
* @package sohbet
* @copyright www.sinavbankasi.com
*/
/**
* Örnek bir nesne için açıklama
*
* Burada nesne hakkında genel bilgiler yazılacak. Ben bu
* nesneyi sohbet isminde bir nesneden türettim dolayısıyla
* belge üretiminde bu sınıfın ilişkili olduğu diğer sınıfları
* "see" etiketiyle belirterek bu açıklama sayfasından sohbet
* sınıfına bağlantı eklenmesini sağlıyorum. "see" etiketi
* etkin olarak kullanılması gereken bir etikettir.
*
* @see sohbet
*/
class sohbet_yonetim extends sohbet
{
/**
* Son X günlük mesajların listesi
*
* Konuya göre gruplandırılmış şekilde açık ve önemli (1 ve 2) mesajların listesini
* bulunduran değişkendir.
*
* Kapalı ve sistem mesajı olarak listelenmiş mesajlar için son 1 günlük kayıtları
* listeler.
*
*
* $liste[0..n]
* 'konu_no'=>integer,
* 'kul_adi'=>string, // Mesajı gönderen kullanıcının adı
* 'son_msj'=>string, // Bu konuda gönderilen son mesaj
* 'son_msj_kuladi'=>string,// Mesaja en son cevap veren kullanıcı
* 'son_msj_tarih'=>date, // Gönderilen son mesajın tarihi
* 'yeni_msj_say'=>integer, // Yeni mesj, yönetici için
* 'son_okuma'=>date, // Yöneticinin o mesajı son okuma tarihi
* 'kul_son_okuma'=>date, // Kullanıcının o mesajı son okuma tarihi
* 'kul_online'=>boolean, // Eğer kullanıcı o mesajı son 3 dak içinde okumuşsa doğru
* 'durum'=>integer, // Mesajın nasıl işaretlendiği (açık, kapalı, önemli..)
*
*
* @access public
* @var array
*/
var $liste = array();
/**
* Mesajların Listesi
*
* Burada çeşitli işlemler yapılarak $liste
* oluşturulmaya çalışılacak.
*
* @return array
* @access public
* @see $liste
*/
function liste()
{
// buraya kodlar gelecek
}
}
?>
Genel Kullanım
Linux için:
phpdoc -t hedefdizin -o HTML:default:default -d cevrilecekdizin
Windows İçin:
C:\>php.exe "C:\phpdoc\yeri\phpdoc" -t hedefdizin -o HTML:default:default -d cevrilecekdizin
hedefdizin: Hazırlanan belgelerin kaydedileceği dizin
cevrilecekdizin: İçerisindeki php dosyalarının okunarak onlardan belge üretilecek olan dizin
Aynı zamanda paketin içerisinden yer alan makedoc.sh dosyasını isteğinize göre değiştirip belge hazırlamayı kolaylaştırabilirsiniz.
phpDocumantor Etiketleri (komutları)
PhpDoc için açıklama yazarken kullanacağımız komutları burada anlatmaya çalışacağım.
Dosya başlığı komutları
/**
* Dosya için genel bir başlık
*
* Hazırlanan dosya için genel açıklama satırları
*
* @author Sinan Yalçınkaya < sinan@sinavbankasi.com >
* @package sohbet
* @copyright www.sinavbankasi.com
* @version 1.0
*/
@author: Programı yazan, eğer birden fazla ise ilk yazardan sonra virgül koyarak diğer yazarlar eklenir
@package: Dosyanın hangi paket altında yer aldığı burada belirtilir
@copyright: Programın telif hakları ile ilgili not bölümü
@version: Programın sürüm bilgileri bu komut ile belirtilir
@access Etiketi
Bu etiket açıklama bloklarının hangilerinin belgede yer alıp almayacağını belirtmekte kullanılır.
Örnek:
/**
* Genel açıklama satırları için erişim bilgisi kullanımı
*
* Varsayılan olarak @access etiketinin değeri "public" yani
* herkese açıktır.
*
* @access public
*/
function acikIslev(){
// komut satırları
}
/**
* "private" (özel) denilerek bu satırların ve altta yer alan
* nesne, değişken, işlev vb.. öğelerin hazırlanan belgede
* gizlenmesi sağlanır.
*
* @access private
*/
function gizliIslev(){
//komut satırları
}
/**
* "protected" (korumalı) denilerek sadece öğeye ait açıklama
* satırlarının (bu okuduğunuz satırların) gizlenmesi
* ancak ilgili öğeye hazırlanan belgede atıfta bulunulması
* sağlanır.
*
* @access protected
*/
function belgedeYerAlacakIslev(){
//komut satırları
}