[tutorial] Auto-tworzenie dokmentacji w PHP

[MWL]

Wstęp

Ten krótki tutorial może okazać się przydatny dla programistów php'u którym nie chce się pisać dokumentacji lub nie mają na to czasu.

Jeśli tworzymy program, to najważniejszą rzeczą zaraz po kodzie źródłowym jest dostarczenie dokumentacji. Opisywać ona powinna wszystkie klasy, funkcji i operacje które dzieją się w programie. Jednak jeśli ilość funkcji jest tak wielka że trzeba zatrudnić dodatkowe osoby tylko i wyłącznie do pisania jej to wiąże się to z kłopotem, nie tylko finansowym, ale także takim że nie jesteśmy pewni czy ludzie pracujący nad dokumentacją dokładnie rozumieją działanie programu. Oczywiście jeśli napisali byśmy sami dokumentację była by ona o wiele lepsza, dlaczego więc sobie nie pomóc i jej po prostu nie wygenerować?

Aby to zrobić wystarczy pobrać program phpdoc. Został on napisany od początku do końca w języku php i dla języka php, więc aby go odpalić potrzebowali będziemy serwera obsługującego język php.

Instalacja

Jeśli nie posiadamy serwera z php'em powinniśmy albo założyć konto na jednym z bezpłatnych hostingów, albo zainstalować sobie pakiet serwera np. krasnal lub xampp (ja osobiście zalecam to 2). Dalej zamieszczamy pobrane pliki na serwerze, i sprawdzamy czy wszystko jest sprawne, jeśli tak to gratulacje, program zainstalowałeś prawidłowo. Teraz zostaje tylko nabrać nawyku odpowiedniego formatowania komentarzy.

Jak działa phpdoc?

phpdoc tworzy dokumentację na podstawie komentarzy, czy zastanawialiście się kiedyś czemu komentarza w bibliotece PEAR wygladają tak a nie inaczej?? To własnie przez phpdoc. Nie bedę opisywał tutaj wszystkiego bo mija się to z celem, natomiast polecam przeczytać artykół na stronie gajdaw o pisaniu komentarzy do phpdoc.



Mam nadzieję że przyda się wam to w pisaniu projektów, powodzenia ;)

ps. Proszę o wyrozumiałość, to mój pierwszy tutorial