PhpDoc w netbeans

Phpdoc jest bardzo przydatnym narzędziem używanym do automatycznego generowania dokumentacji z kodu. Ma on jednak poza tym jeszcze inne zastosowania.

Jednym z nich, a właściwie zastosowaniem jego tagów jest pomoc w podpowiadaniu kodu. Jako, że większość swoich projektów php-owych pisze w Netbeans, postanowiłem przybliżyć kilka sposobów na ułatwienie sobie życia.

Jeszcze krótkim słowem wstępu, jak wyglądają tagi phpdoc-a ?

/**
* @param integer $a
*/
function foo($a){
    return $a+1;
}

Jak widzimy tagi pisane są w komentarzu, który zaczyna się od dwóch gwiazdek ‚/**’ i znaku nowej linii. Otwierając komentarz i pisząc właśnie ‚/**’ i wciskając enter, netbeans sam wstawi nam template do uzupełnienia tagów.

Pytanie teraz, jak tagi phpDoc-a mogą nam ułatwić życie, poprawić komfort pisania kodu ? To proste, w php nie da się deklarować typu zmiennych oraz tworzyć typowanych argumentów funkcji (oprócz typowania na klasy i interfejsy). Wobec tego IDE ma ograniczone możliwości podpowiadania. Co więcej, gdy używamy magicznych funkcji __get i __set, sprawa staje się jeszcze bardziej beznadziejna.

Przydatne tagi i przykłady zastosowania:

  • /*@var $zmienna NazwaKlasy */ – używany wewnątrz funkcji, działa jak deklaracja typu zmiennej w językach statycznie typowanych, np. C czy Javie (tag obsługiwany tylko w netbeans)
  • @var TypParametru – używany w klasie przed deklaracją właściwości klasy
  • @param TypParametru $zmienna – używany przed deklaracją metody/funkcji mówi jaki typ ma parametr przekazywany do funkcji
  • @property TypParametru $zmienna – używany przed deklaracją klasy, informuje o właściwościach klasy implementowaych przez magiczne metody __get i __set
  • @property-read – j.w tylko dla właściwości tylko do odczytu
  • @property-write – j.w tylko dla właściwości tylko do zapisu
  • @method TypZwracany nazwaMetody() – używany przed deklaracją klasy, deklaruje metodę implementowaną przez magiczną metodę __call
  • @return TypZwracany – informuje o typie zwracanym przez funkcje/metodę

Dzięki stosowaniu tych tagów w swoich projektach, można wymiernie poprawić swoją efektywność w pisaniu kodu, oraz jako skutek uboczny mieć automatycznie wygenerowaną podstawową dokumentacje.

P.S inne edytory też to obsługuja (np. Eclipse)

  1. Adam pisze:

    /*@var $zmienna NazwaKlasy */ jest obsługiwane w PDT 1.x oraz 2.1, ale nie w 2.0.

  2. Wojciech Soczyński pisze:

    Dobrze wiedzieć, jak bym się miał przesiadać 😉

  1. There are no trackbacks for this post yet.

Leave a Reply

Informuj mnie o odpowiedziach poprzez e-mail. Możesz również subskrybować wpis bez zostawiania komentarza.