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)
/*@var $zmienna NazwaKlasy */ jest obsługiwane w PDT 1.x oraz 2.1, ale nie w 2.0.
Dobrze wiedzieć, jak bym się miał przesiadać 😉