phpDocumentor ile PHPDoc oluşturun

Bir yazılımı üretirken, yazılımcıya birçok iş düşer. Bu işler arasında, önem seviyesi çok yüksek olan bir iş vardır: Döküman!

Ancak yazılımı üretirken bir yandan da yazılımda neyin nasıl çalıştığını belgelemek her ne kadar kolay görünse de oldukça zor bir iştir. Bunun için genelde; metotların ve sınıfların, kıyısına köşesine yorum satırları eklenir. Bu metot şu işi yapar, bu class şunu yapar şeklinde…

Programlama dillerinde birçok şeyin standardı olduğu gibi kendi içlerinde yorum yazmanın da bir standardı var. Örneğin bir metota ait yorum satırında olabilecek şeyler: Sınıfa metodu kim ekledi, metodun görevi nedir, geriye ne döndürür, daha sonra metotta yapılacak ekstra işlem (todo) var mı vs. vs.

Eğer bu standartlara uyarak yorum eklerseniz, ödül olarak güzel bir PHPDoc elde edebilirsiniz.

Doc nedir?

Standartlara uygun yazılmış yorum satırlarını parse edip, liste halinde sınıflar ve metodlar hakkında çeşitli bilgiler sunulan döküman.

Doc neden kullanılmalı?

Sizden sonra gelecek olan yazılımcıya, hiç yüzünü dahi görmeden kodları anlatmanız gerekir. Gerekir, çünkü o kodların bir şekilde devamı gelmelidir. Böylece sizden başkaları, hatta kendiniz için bile bir yol haritası çizmenizi sağlar Doc’lar.

Yıllar evvel yazdığınız bir koda geri dönmeniz gerekti diyelim. Şansa bakın ki o yazdığınız kodları kendiniz belgelemiştiniz zamanında. Ama yıllar geçtiği için belgeler de bir şekilde uçmuş. Elde sadece kodunuz var.

Eğer yorum satırları standartlara uygun bir şekilde yazılmışsa, bir doc parser ile kodu parse edip elinize hemen bir döküman alabilirsiniz.

PHPDoc Nasıl Oluşturulur?

PHPDoc oluşturmak için, phpDocumentor isimli bir PEAR eklentisi mevcut.

Yüklemek için:

pear channel-discover pear.phpdoc.org
pear install phpdoc/phpDocumentor-alpha

phpDocumentor için sisteminizde Graphviz ve PHP XSL yüklü olmalı.

Hızlıca bir projenin phpDoc’unu çıkarmak için:

phpdoc -d /var/www/test -t /var/www/docs

ardından http://localhost/docs adresinden projenizin phpDoc’unu görebilirsiniz.

Eğer tek 1 dosyanın Doc’unu çıkarmak isterseniz:

phpdoc -f /var/www/test/index.php -t /var/www/docs

Absolute path vermek zorunda değilsiniz.

PHPDoc oluşturmaya giriş

Yazının sonunda daha detaylı bilgi alabileceğiniz bir adres verdim. Ama yine de bir giriş yapayım dedim.

  • Yorum satırları /** ile başlamalıdır. Her satırın başında * olmalıdır.
  • Her dosyanın bir açıklaması olmalıdır.
  • phpDocumentor, namespace’lere göre de parse işlemi yapar.
  • Oluşan Doc’ta hangi dosyanın, hangi satırındaki yorum syntax’ında hata var gösterilir.

Efenim, sözün özü: phpDoc’u kullanın, kullandırtın.

phpDoc hakkında daha detaylı bilgi phpdoc.org adresinde.

 
22 Kudos
Don't move
  1. kurulum kısmını biraz açarmısınız. örneğin windows üzerine nasıl kurabiliriz bunu.

Yorum Yap


Not - Bunları KullanabilirsinizHTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>