Prawda jest taka, że kod bez dokumentacji to zazwyczaj katorga dla osoby z nim pracującej. W mniejszych projektach może nie stanowi to większego problemu, ale w przypadku, gdy mamy do czynienia z dużymi projektami składającymi się z dużej ilości rozbudowanych klas brak dobrej dokumentacji jest wręcz dla takiego kodu dyskwalifikacją. Dobra dokumentacja powinna składać się z kilku elementów - po pierwsze: musi ona być. Po drugie - musi ona trzymać się pewnych standardów, takich jak sposób opisu danej klasy, jej metod, czy własności. Z koleji przy dokumentacji metod i funkcji w dokumentacji powinień znaleźć się opis pobieranych i zwracanych parametrów, a także opis ich typów. Wszelkie tego typu kluczowe informacje powinny się w dokumentacji znaleźć i powinny zostać podane w pewien ustandaryzowany sposób.
Pakiet phpDocumentator wymusza na programiście pewien schemat dokumentowania kodu i radzę się tego schematu trzymać w każdym swoim projekcie, nawet jeśli nie mamy zamiaru przygotowywać do niego zewnętrznej dokumentacji za pomocą narzędzi takich jak phpDocumentator. Składnia taka po prostu jest powszechna wśród programistow i co za tym idzie - zostanie szybko zrozumiana przez innego programistę pracującego z naszym kodem. W artykule tym na początku omówimy sobie wszystkie aspekty tego jak poprawnie powinna taka dokumentacja wyglądać, a na sam koniec zobaczymy co z tak przygotowanej dokumentacji potrafi wygenerować nam phpDocumentator.
Strona oficjalna phpDocumentatora to: http://phpdoc.org/.
