Temat: Za co się teraz zabrać?
Kolega, trochę przesadzasz. Doskonale znam narzędzia do dokumentowania kodu. I tak jak pisałem, PHPdoc *jest* używany również jako symulowanie statycznego typowania.
Dariusz Półtorak:
2. Od razu wiem jakie typy zwraca dana metoda bo to KAŻDA NIEJASNOŚĆ powinna być opisana w phpDoc. A robi się to dziecinnie prosto:
@return Foo | Bar
Świetnie, właśnie zadeklarowałeś typy, jakie zwraca metoda. W Javie czy C# tego się nie robi, bo typ jest określony w sygnaturze metody. W PHP wpisujesz typ bo... nigdzie indziej go wpisać nie możesz. I tak, wypada to zrobić na potrzebę dokumentacji. Ale w języku statycznie typowanym zostanie to wyjęte automatycznie, nie podaje się tego "dodatkowo", a tag @return służy do OPISANIA co jest zwaracane, a nie jaki jest tego typ.
Źle. IDE będzie nadal podpowiadać. Od tego jest phpDoc. Nic nie trzeba analizować. Nie trzeba tracić czasu.Nie trzeba robić nic. Po prostu z pomocą prostego wpisu phpDoc który programista ma zrobić IDE będzie w pełni podpowiadać. Nawet dokumentacji nie trzeba.
No właśnie, parę postów wyżej pisałeś, że:
string nazwaMetody()
{...}
to nadmierne komplikowanie, a teraz piszesz, że:
/**
* @return string
*/
function nazwaMetody()
{...}
jest w porządku i każdy powinien robić... :) Nie będę wskazywać, co ma mniej znaków i jest czytelniejsze :) Poza tym, widzisz, to jest pomoc dla programisty, pod warunkiem, że sobie to dopisze! PHP tego nie wymaga i początkujący programista się tego nie nauczy. Język statycznie typowany wymusi na nim podawanie typów i nauczy zachowywać porządek.
Znowu źle. Tą samą robotę robiłem jak pisałem w C++ czy w Javie. Parametry trzeba opisać tak czy siak. phpDoc to właściwie to samo co javaDoc itp. Praktycznie się nie różni.
Dokładnie, opisywać. W swoich przykładach nie zrobiłeś opisu, tylko podałeś, co metoda zwraca. Opis wyglądałby tak (z opisu JavaDoc ze strony Oracle, zauważ BRAK podania typu):
* @return the image at the specified URL
Każdy normalny projekt ma tego typu komentarze. Każda normalna klasa. Różnica polega na tym że IDE w PHP wykorzystują je żeby podpowiadać tam gdzie nie idzie wyczaić typu z kodu źródłowego.
Nie każdy, bo przy statycznym typowaniu *takie* komentarze nie są w ogóle potrzebne :)
Jeżeli tego jeszcze nie robisz to po prostu musisz się tego nauczyć. Bywa. Dokumentowanie kodu nie jest zależne od języka w żadnym wypadku.
Oczywiście, że jest - zależy od tego, jak wiele narzędzie do dokumentowania kodu jest w stanie wyciągnąć z kodu samego w sobie. W przypadku PHP może wyciągnąć bardzo mało, stąd w PHPdoc musisz wpisywać więcej rzeczy, żeby dokumentacja miała ręce i nogi :)