PHP - dokumentacja

Odnosniki do projektow

• PHPDoc
• PHPAutodoc
• PHPCodedoc

PHPDoc

Strona domowa: www.phpdoc.de
Najnowsza wersja: phpdoc1beta.zip

Zalety

• działa!!!,
• generuje ładnie wyglądającą dokumentację,
• łatwe dostosowywanie do własnych potrzeb
• obsługa XML'a

Wady

• brak prawdziwego parsera
• ograniczenia na pliki źrodłowe, nie można mieszać kodu obiektowego z nieobiektowym, tylko jedena klasa na plik

Instalacja

• phpdoc wymaga zainstalowania php z obsluga XML'a i PCRE (Perl Compatible Regular Expresions)
• odpakowanie pakietu
• ustalenie poprawnych wartości następujących stałych (w pliku index.php)
  • PHPDOC_INCLUDE_DIR
  • PHPDOC_LINEBREAK
• zdefiniowanie projektu dla którego ma zostać wygenerowana dokumentacja (również plik index.php)
  • $doc->setApplication("PHPDoc"); --- nazwa projektu
  • $doc->setSourceDirectory("/var/www/src"); --- katalog ze źródłami
  • $doc->setTarget("/var/www/doc"); --- gdzie ma iść dokumentacja (należy pamiętać o odpowiednich prawach dostępu)
  • $doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/"); --- domyślne szablonu dokumentów
  • $doc->setSourceFileSuffix( array ("php", "inc") ); --- rozszerzenia plików źródłowych PHP
• Dla dużych projektów generowanie dokumentacji może trwać dosyć długo, stąd może okazać się konieczne zwiększenie stałej max_execution_time w pliku php.ini
• katalog z dokumentacja należy uzupłenić o pliki index2.html, empty.html, phpdoc.css (można je znaleźć w katalogu apidoc/keep/)

Dokumentowanie kodu źródłowego

PHPDoc wykorzystuje specjalnie sformatowane kometarze do generowanie dokumentacji (to rozwiązanie zostało zapożyczone z JavaDoc). Przykładowy komentarz:

/**
 * krótki opis f-ji/modułu
 *
 * tu można dodać dłuższy opis
 *
 * @param        typ_parametru $nazwa_parametru  opis_parametru
 * @see	         do() 
 */

Komentarze rozpoznawane przez PHPDoc muszą rozpoczynać się od znaków

/**

Oprócz krótkiego opis tekstowego f-ji można dodać dokładniejszy opis, do tego służa polecenia typu:

 * @polecenie param1 param2 ...

Dostępne polecenia:

• @param typ nazwa opis --- dodanie opisu parametru f-ji
• @see co --- odnosnik do innego obiektu/f-ji
• @abstract --- znaznaczenie, że f-ja jest abstrakcyjna
• @return co --- jakiego typu jest wynik
• @version ver --- wersja
• @author autor <email> --- dodanie informacji o autorze