Dokumentacja oprogramowania jest często równie istotna, jak samo oprogramowanie. Stwierdzenie to jest szczególnie prawdziwe w odniesieniu do wielokrotnie wykorzystywanych bibliotek. Artykuł omawia instalację i uruchamianie PhpDocumentatora, a także wyjaśnia składnię komentarzy, na podstawie których PhpDocumentator tworzy dokumentację skryptów.
W celu uniknięcia konieczności tworzenia dokumentacji całego kodu po ukończeniu projektu, stosuje się automatyczne systemy dokumentowania. W świecie Javy prym wiedzie JavaDoc, w kręgu C++ mamy do dyspozycji między innymi DOC++ oraz doxygen, natomiast środowisko programistów PHP wykorzystuje aplikację PhpDocumentator.
Rodzaje dokumentacji
Dokumentację kodów źródłowych programów komputerowych dzielimy na dwie kategorie:
dokumentacja API (ang. Application Program Interface),
dokumentacja szczegółowa, wyjaśniającą metody implementacji.
Dokumentacja API zawiera opis, który umożliwia wykorzystanie danej funkcji, klasy czy biblioteki do własnych celów. W odniesieniu do funkcji zawiera ona zazwyczaj opis parametrów wejściowych (ich typ i rolę) oraz informacje o generowanym wyniku.
Drugi rodzaj dokumentacji opisuje szczegóły implementacyjne konkretnego fragmentu kodu (np. funkcji czy nawet pojedynczej pętli lub instrukcji if). Uwagi tego typu są pomocne, jeśli chcesz zrozumieć, jak dany kod działa.
Przykładem dokumentacji API jest oczywiście duża część podręcznika PHP, w szczególności dział Function Reference. Na przykład przy opisie funkcji {stala}str_replace(){/stala} znajdziesz między innymi informację o wersji PHP od której funkcja jest dostępna:
(PHP 3>= 3.0.6, PHP 4)
jej nagłówek:
mixed str_replace(mixed search, mixed replace, mixed subject [, int &count])
krótkie wyjaśnienie jej roli:
str_replace -- Replace all occurrences of the search string with the replacement string
oraz opis działania.
Natomiast przykładem drugiego rodzaju dokumentacji są komentarze zawarte w pliku Smarty_Compiler.class.php. W linijce 177 znajdziesz wyjaśnienie:
Powyższy opis jest istotny dopiero wtedy, gdy zechcesz zrozumieć, w jaki sposób Smarty kompiluje pliki .tpl na wynikowy skrypt PHP.
Dokumentacja API skryptów PHP
Do generowania dokumentacji API skryptów w PHP służy aplikacja phpDocumentator. Dokumentacja generowana systemem PhpDocumentator powstaje na podstawie skryptów źródłowych PHP. Nie trzeba przygotowywać żadnych dodatkowych plików. Opis, jaki zostanie zawarty w dokumentacji, jest umieszczany w skryptach PHP w postaci specjalnych komentarzy.
Listing 1 prezentuje kod funkcji wyznaczającej większą z dwóch liczb. Funkcję poprzedza specjalny komentarz nazywanym blokiem dokumentacji. Blok taki zawiera tekst sformatowany za pomocą kilku znaczników HTML oraz specjalne napisy rozpoczynające się od znaku @ (na listingu są to napisy @param).
/**
* Maksimum z dwóch liczb
*
* Funkcja wyznacza większą z dwóch liczb.
*
* Przykładowe wywołanie:
*
*
* $x = 13;
* $y = 44;
* $z = max($x, $y);
*
*
* Funkcja nie sprawdza typu otrzymanych parametrów.
*
* @param integer pierwsza liczba
* @param integer druga liczba
*/
function max($a, $b)
{
if ($a > $b) {
return $a;
} else {
return $b;
}
}
Po przetworzeniu skryptu PHP, program PhpDocumentator utworzy pliki zawierające dokumentację, w której znajdą się informacje pochodzące z bloków. Można powiedzieć, że skrypt PHP wzbogacony o bloki dokumentacyjne przeznaczony jest dla dwóch odbiorców:
maszyny PHP
aplikacji PhpDocumentator
Maszyna PHP interpretuje kod PHP. Nie interesują jej komentarze (ani bloki dokumentacji, ani żadne inne). Natomiast program PhpDocumentator interesuje się głównie (choć nie tylko) blokami dokumentacji i na ich podstawie generuje dokumentację. Na podstawie listingu 1 została wygenerowana dokumentacja przedstawiona na ilustracji 1.
Aplikacja PhpDocumentator
Instalacja oprogramowania
Najnowsza wersja systemu PhpDocumentator ma numer 1.3 i jest rozpowszechniana w postaci spakowanego archiwum PhpDocumentor-1.3.0RC4.tgz. Plik ten znajdziesz na stronie domowej projektu pod adresem http://www.phpdoc.org.
Instalacja pakietu sprowadza się do rozpakowania archiwum. Ponieważ PhpDocumentator jest w całości napisany w języku PHP, a interfejsem programu są formularze HTML, zatem wypakowane pliki należy umieścić w folderze widocznym z poziomu WWW. (Jeśli korzystamy z nowej wersji serwera Apache w systemie Windows, to domyślnie folder ten nazywa się C:\\Program .les\\ApacheGroup\\Apache2\\htdocs).
Po zainstalowaniu pakietu, uruchom przeglądarkę internetową i po wprowadzeniu adresu localhost odwiedź witrynę zawartą w wypakowanym folderze. Rys. 2 przedstawia stronę, jaką powinieneś ujrzeć.
Pierwsze uruchomienie
Przed przystąpieniem do pierwszego uruchomienia aplikacji PhpDocumentator musisz przygotować skrypt PHP, jaki poddasz przetwarzaniu. Do tego celu możesz wykorzystać skrypt z listingu 1.
Utwórz dwa foldery: folder, z którego PhpDocumentator będzie pobierał pliki do przetworzenia oraz folder przeznaczony na wygenerowaną dokumentację. Foldery te nazwij na przykład G:\\phpdoc\\in (folder z danymi) oraz G:\\phpdoc\\out (folder przeznaczony na wyniki). W folderze G:\\phpdoc\\in umieść plik max.php zawierający skrypt z listingu 1.
Gdy foldery są gotowe, możesz przystąpić do pierwszego uruchomienia programu. Interfejs aplikacji PhpDocumentator składa się z serii formularzy, dostępnych za pośrednictwem przeglądarki internetowej. Uruchom przeglądarkę, wprowadź adres localhost, po czym odwiedź stroną główną aplikacji PhpDocumentator.
Z menu głównego aplikacji wybierz opcję Files. Następnie w polu Files to parse wprowadź nazwę pliku G:\\phpdoc\\in\\max.php. W ten sposób wskazujesz, jakie pliki należy poddać przetwarzaniu (ilustracja 3).
Teraz przejdź do opcji Output z menu głównego aplikacji PhpDocumentator. W polu Target wprowadź nazwę folderu G:\\phpdoc\\out. Jest to folder, w jakim PhpDocumentator będzie zapisywał wygenerowaną dokumentację.
Ostatnim krokiem jest wygenerowanie dokumentacji. Po naciśnięciu przycisku Create w folderze docelowym zostanie umieszczona gotowa dokumentacja (rysunek 4). Dokumentacja wygenerowana dla pliku max.php jest przedstawiona na ilustracji 5.
Zmiana formatu generowanej dokumentacji
PhpDocumentator umożliwia generowanie dokumentacji w wielu różnych formatach, między innymi HTML, PDF oraz CHM. Do wyboru formatu dokumentacji służy lista rozwijana, widoczna na rys. 6.
Po wybraniu odpowiedniej pozycji z listy wyboru należy nacisnąć opcję: Add the converter in the help box, dostępną poniżej listy wyboru. Wybrany format zostanie dodany do pola Output format (ilustracja 7). W ten sposób możesz wygenerować dowolną liczbę formatów pojedynczym uruchomieniem aplikacji. W przypadku wybrania kilku formatów każdy format zostanie zapisany w oddzielnym folderze.
Rys. 8 przedstawia dokumentację w formacie HTML:frames:earthli wygenerowaną dla pliku max.php.
Opcje konfiguracyjne
Opcje konfiguracyjne programu są dostępne po wybraniu zakładki Options w menu głównym. Znajdziesz tam między innymi pola Generated Documentation title, Default Package Name oraz Default Category Name. Pola te umożliwiają ustalenie tytułu generowanej dokumentacji, nazwę domyślnego pakietu oraz kategorii.
Ponadto zaznaczenie pola wyboru Generate Highlighted Source Code powoduje, że dokumentacja będzie zawierała kompletne pliki źródłowe z ponumerowanymi liniami, wzbogacone o odwołania hipertekstowe. Pole Parse @access private umożliwia dołączenie do dokumentacji także elementów kodu o dostępie prywatnym.
Składnia dokumentacji zawartej w kodzie PHP
Bloki
Podstawową jednostką dokumentacji jest blok (ang. documentation block) określany również jako DocBlock. Blok jest komentarzem postaci:
/**
*
*
*
*/
Należy zwrócić uwagę na dwa znaki * w pierwszej linii. Każda linijka musi rozpoczynać się znakiem *, w przeciwnym razie zostanie zignorowana. Tekst dokumentacji umieszczamy po znakach *, przy czym pierwszą linijkę pozostawiamy pustą:
/**
* Lorem ipsum
* Dolor sit amet
*/
Blok należy umieszczać bezpośrednio przed dokumentowanym elementem kodu. Na przykład blok dotyczący funkcji {stala}f(){/stala} umieszczamy bezpośrednio przed funkcją {stala}f(){/stala} (bez żadnej pustej linijki):
Jeżeli pomiędzy blokiem a dokumentowaną funkcją {stala}f(){/stala} umieścimy definicję stałej {stala}nothing{/stala}, to blok dotyczy nie funkcji {stala}f(){/stala}, a stałej {stala}nothing{/stala}:
Pierwszy blok w pliku ma specjalne znaczenie: dotyczy całego pliku. Jest on nazywany blokiem głównym (ang. Page-level block). Blok główny jest rozpoznawany na podstawie tego, że występuje jako pierwszy. Dodatkowo powinien on zawierać znacznik @package lub bezpośrednio po nim należy umieścić inny blok, a nie dokumentowalny element. Niedopuszczalną sytuacją jest blok główny, pozbawiony znacznika @package, po którym występuje dokumentowalny element, na przykład stała:
/**
* Blok główny
*
* Lorem ipsum...
*/
define(\'ble\',0);
W powyższym przykładzie blok nie jest blokiem głównym. Blok ten dotyczy stałej ble. Problem ten możesz rozwiązać na dwa sposoby:
dodając znacznik @package:
/**
* Blok główny
*
* Lorem ipsum...
*
* @package Example
*/
define(\'ble\',0);
lub dodając blok stałej ble:
/**
* Blok główny
*
* Lorem ipsum...
*/
/**
* Blok stałej ble
*
* Lorem ipsum...
*/
define(\'ble\',0);
Ponieważ PhpDocumentator służy do generowania dokumentacji API, bloki nie mogą być stosowane do dokumentowania fragmentów kodu wewnątrz funkcji. Poniższy blok użyty wewnątrz funkcji {stala}lorem(){/stala} nie ma żadnego sensu:
function lorem()
{
/**
* Instrukcja while...
*
* Lorem ipsum...
*/
while ($tmp) {
...
}
}
Struktura bloku
Każdy DocBlock składa się z trzech części: opisu krótkiego, opisu długiego oraz znaczników dokumentacji:
/**
* Opis krótki
*
* Opis długi lorem ipsum
* dolor sit amet
*
* @author Znacznik dokumentacji
*/
Opis długi oraz znaczniki są opcjonalne i mogą nie wystąpić. Jako opis krótki jest traktowany pierwszy tekst występujący w bloku, nawet wtedy, gdy początkowe linie zostawisz puste:
/**
*
*
*
*
* Ten tekst będzie krótkim opisem
*
*/
Krótki opis kończy się pustą linią lub kropką. Jeśli krótki opis zajmuje więcej niż trzy linie, to brana jest tylko pierwsza linia. Opis długi może liczyć dowolnie wiele linii. Tekst może być podzielony na akapity i zawierać niektóre znaczniki HTML.
Natomiast znaczniki dokumentacji rozpoczynają się od znaku @. Są one zazwyczaj umieszczone na końcu bloku i muszą (w przeciwnym razie nie są traktowane jak znaczniki szablonu, a jak zwykłe napisy) występować zaraz po znaku * (oraz ewentualnych spacjach):
/**
* Opis krotki
*
* Opis dlugi lorem
* ipsum dolor
* sit amet...
*
* @link http://example.com
* @copyright 2001-2005 Example
* @author Mr Example
*/
Podział długiego opisu na akapity
Tekst długiego opisu może być podzielony na akapity. Do podziału opisu długiego na akapity służą:
znaczniki {html}
{/html} oraz {html}
{/html}
puste linie
Należy wybrać jeden ze sposobów i stosować konsekwentnie. Jeśli pierwszy akapit nie rozpoczyna się od znacznika {html}
{/html}, to PhpDocumentator przyjmie, że akapity są definiowane przez puste linie. Oto przykładowy blok zawierający dwa akapity:
/**
* Opis krótki
*
* Akapit pierwszy...
*
* Akapit drugi...
*/
Puste linie
Nadmiarowe puste linie są ignorowane. Tam, gdzie występuje jedna pusta linia, możesz umieścić wiele pustych linii:
/**
* Opis krótki
*
*
*
* Lorem ipsum...
*
*
*
* Dolor sit amet...
*
*
* @author Cycero
*/
Kod HTML stosowany w blokach
Bloki mogą zawierać znaczniki, których znaczenie jest niemal identyczne jak w języku HTML. Jedyna różnica dotyczy elementów {stala}pre{/stala} oraz {stala}code{/stala}. Obydwa służą do umieszczania fragmentu kodu. W przypadku użycia code kod będzie pokolorowany. Oto przykład użycia znaczników {html}{/html}, {html}{/html} oraz wypunktowania:
/**
* Opis krótki
*
* Opis długi lorem ipsum
* dolor sit amet:
*
*
A
*
B
*
*
* @link http://example.com
* @copyright 2001-2005 Example
* @author Mr Example
*/
Znaczniki HTML możesz zapisywać dużymi lub małymi literami. Znacznik br może być zapisywany tak jak w języku HTML ({html} {/html}) lub tak jak w języku XTHML ({html} {/html}). Wewnątrz elementów {stala}code{/stala} oraz {stala}pre{/stala} nie można stosować kodu HTML.
Automatyczne numerowanie i wypunktowanie
Warto wiedzieć, że listy numerowane oraz wypunktowane można tworzyć nie tylko przy użyciu elementów {stala}ol{/stala}, {stala}ul{/stala} i {stala}li{/stala}, ale także stosując prosty format tekstowy. Rozpoznawalnymi formatami wypunktowania są kolejne linie rozpoczynające się od znaków {stala}-{/stala}, {stala}+{/stala}, {stala}#{/stala}, {stala}o{/stala}, na przykład:
+pozycja pierwsza
+pozycja druga
+pozycja trzecia
W przypadku numerowania, rozpoznawalnymi formatami są liczby arabskie oraz litery:
1. Pozycja pierwsza
2. Pozycja druga
3. Pozycja trzecia
Cytowanie kodu HTML
Do cytowania kodu HTML stosuj podwójne znaki {html}<<{/html} oraz {html}>>{/html}:
/**
* Opis krótki
*
* Lorem <>ipsum<> dolor
* sit <>amet<>
*/
Użycie w bloku znaku końca komentarza PHP
Jeśli natomiast w bloku chcesz umieścić napis kończący komentarz PHP, czyli {stala}*/{/stala}, to należy użyć sekwencji {stala}{@*}{/stala}:
/**
* Opis krótki
*
* Blok DocBlock ma postać:
*
*
* /**
* *
* *
* {@*}
*
*
*/
Szablony bloków
Treść, która powtarza się w kilku kolejnych blokach, może być ustalona za pomocą szablonu (ang. DocBlockTemplate). Szablon rozpoczyna się od bloku:
/**#@+
*
*/
a kończy blokiem:
/**#@-*/
Treść występująca w znaczniku otwierającym blok będzie umieszczana wewnątrz wszystkich bloków, aż do bloku kończącego szablon. Na przykład w dokumentacji poniższej klasy Example:
class Example
{
/**#@+
*
* Lorem ipsum
*/
/**
* Pole one...
*/
var $one;
/**
* Pole two...
*/
var $two;
/**#@-*/
/**
* Pole three...
*/
var $three;
}
opisy pól {stala}$one{/stala} oraz {stala}$two{/stala} zostaną wzbogacone o tekst \”Lorem ipsum\”. Blok opisujący pole {stala}$three{/stala} znajduje się poza szablonem (poniżej bloku {stala}/**#@-*/{/stala}), a zatem opis pola {stala}$three{/stala} nie będzie zawierał tekstu \”Lorem ipsum\”.
Znaczniki dokumentacji
Ostatnim rodzajem wpisów, jakie występują w blokach, są znaczniki dokumentacji (ang. tags). Znaczniki dokumentacji rozpoczynają się od znaku @ i zawierają dodatkowe informacje umieszczane w dokumentacji. Przykładami znaczników są @author oraz @version. Pierwszy z nich ustala imię, nazwisko oraz adres emailowy autora, zaś drugi wersję dokumentowanego skryptu.
Znaczniki są podzielone na dwie grupy: standardowe oraz specyficzne. Znaczniki standardowe mogą się znaleźć wewnątrz każdego bloku. Natomiast znaczniki specyficzne są przeznaczone dla pewnych wybranych bloków. Tabela 1 przedstawia wszystkie znaczniki standardowe, a tabela 2 – znaczniki specyficzne.
Pamiętaj, że znaczniki dokumentacji są rozpoznawane tylko na początku linii. W poniższym przykładzie żaden z napisów @copyright, @example ani @ignore nie jest znacznikiem dokumentacji (znacznikami są napisy @version oraz @author, gdyż występują na początku linii, tj. zaraz po znaku *):
/**
* Opis
*
* Tutaj napisy @copyright oraz @example nie
* są tagami
*
* @version 0.1.2.3
* @author Napis @ignore nie jest tagiem!
*/
Użycie znaczników w blokach
Znaczniki w bloku głównym
Blok główny (ang. page-level DocBlock) może zawierać znaczniki standardowe oraz:
@package
@subpackage
@category
W pliku musi wystąpić przynajmniej jeden dokumentowalny element zawierający blok.
/**
* Przykładowy blok główny
*
* Lorem ipsum...
*
* @category Examples
* @package EX
* @subpackage EX-typical
* @access public
* @author J. Example
* @copytight 2006 J. Example
* @link http://example.net/PackageEX/
* @since 0.1.2.3 2005/11/28
* @version 1.2.3.4 2006/12/29
*/
Wartości znacznika @package podlega dziedziczeniu. Wszystkie bloki w danym pliku pozbawione znacznika @package odziedziczą wartość znacznika @package bloku głównego.
Bloki dokumentujące instrukcje {stala}include{/stala}, {stala}include_once{/stala}, {stala}require{/stala}, {stala}require_once{/stala} mogą zawierać wyłącznie znaczniki standardowe.
/**
* Opis krótki
*
* Opis długi...
*
* @example C:/example/lorem.php
* @see dolor
*/
require_once \'Lorem.class.php\';
W powyższym przykładzie wyraz dolor występujący po znaczniku @see może być nazwą klasy, funkcji, stałej lub zmiennej.
Zmienne globalne
Blok opisu zmiennej globalnej może zawierać znaczniki standardowe oraz @name:
/**
* Krótki opis
*
* Długi opis...
*
* @name options
* @global int $EXAMPLE_PACKAGE_options
*/
$EXAMPLE_PACKAGE_options = 1;
Stałe
Bloki dotyczące stałych (definiowanych za pomocą define) mogą zawierać znaczniki standardowe oraz znacznik @name:
/**
* Krótki opis
*
* Długi opis...
*
* @name TRUTH
*/
define(\'EXAMPLE_PACKAGE_TRUTH\',true);
Funkcje
Blok opisujący funkcje może zawierać – oprócz znaczników standardowych – także znacznik:
@global (dokumentuje użycie zmiennej globalnej wewnątrz funkcji)
@param (dokumentuje parametry funkcji: ich typ oraz rolę)
@return (dokumentuje wynik zwracany przez funkcję)
@staticvar (dokumentuje użycie wewnątrz funkcji zmiennej statycznej)
{@source} (dołącza do dokumentacji kod źródłowy funkcji)
/**
* Opis krótki
*
* Opis długi...
*
* @global int służy do...
* @param string Dolor służy do ...
* @param string Sit służy do ...
* @return string wynik zawiera...
*
*/
function loremIpsum($Dolor, $Sit)
{
global $Amet;
...
return $Dolor . $Amet;
}
Klasy
Blok klasy może zawierać znaczniki standardowe oraz:
@package
@subpackage
@abstract
Pola klasy
Blok dotyczący pola klasy może zawierać znaczniki standardowe oraz znacznik @var. Znacznik ten ustala typ pola klasy.
Metody klasy
Blok dotyczący metody klasy może zawierać znaczniki standardowe oraz znaczniki:
@global
@param
@return
@abstract
@access
@final
@static
@staticvar
{@source}
Stosując kod PHP4 należy posługiwać się znacznikami @abstract, @access, @.nal,@static:
/**
* Klasa Example
*
* Opis długi...
*
* @author J. Another Example
*
*/
class Example
{
/**
* Opis krótki
*
* Opis długi pola $Field.
*
* @access private
* @var string
*/
var $Field;
/**
* Opis krótki
*
* Opis długi metody method()
*
* @access public
* @static
* @return bool
*/
function method()
{
return true;
}
}
Natomiast w przypadku języka PHP w wersji 5, wartości znaczników @abstract, @access, @static zostaną ustalone na podstawie specyfikatorów dostępu {stala}private{/stala}, {stala}protected{/stala}, {stala}public{/stala} oraz słów kluczowych {stala}static{/stala} i {stala}abstract{/stala}. Konieczne jest jedynie – pomimo obecności w PHP5 słowa kluczowego final – użycie znacznika @final.
class Example
{
/**
* Opis krotki
*
* Opis dlugi metody methodPublicStatic()
*
* @return bool
*/
public static function methodPublicStatic()
{
return true;
}
/**
* Opis krotki
*
* Opis dlugi metody methodPublicFinal()
*
* @final
* @return bool
*/
public final function methodPublicFinal()
{
return true;
}
/**
* Opis krotki
*
* Opis dlugi metody methodPublicAbstract()
*
* @return bool
*/
public abstract function methodPublicAbstract()
{
return true;
}
}
Przykłady
pakiet PL
Pakiet PL składa się z trzech plików: pl.inc.php, string.inc.php oraz pl-constants.inc.php. Pierwszy i drugi z plików zawierają wyłącznie funkcje, zaś trzeci wyłącznie stałe i zmienne globalne. Każdy z plików rozpoczyna się blokiem głównym. Blok ten, przedstawiony na listingu 2, zawiera następujące informacje:
Każda z funkcji zawartych w pliku pl.inc.php posiada swój własny blok dokumentacyjny. W blokach użyto znaczników @param oraz @return opisujących parametry oraz wynik zwracany przez funkcję. Przykładowa funkcja wraz z towarzyszącym jej blokiem są widoczne na listingu 3.
Stałe i zmienne zdefiniowane w pliku pl-constants.inc.php są również poprzedzone blokami. Bloki stałych zawierają wyłącznie krótki oraz długi opis (listing 4), zaś bloki zmiennych globalnych wykorzystują dodatkowo znacznik @global (listing 5).
/**
* Polskie znaki diakrytyczne
*
* Bez ogonkow: asxASX
*
* Kodowanie: iso-8859-2
*
* Litery: male i duze
*
* Tylko litery specyficznedlakodowaniaiso-8859-2
*
* Porzadek: alfabetyczny, najpierw male, potem duze
*/
define(\'PL_ISO_SPECIFIC\',\"\xb1\xb6\xbc\xa1\xa6\xac\");
/**
* Tablica polskich znakow
*
* Bez ogonkow: asxASX
*
* Kodowanie: windows-1250
*
* Litery: male i duze
*
* Litery specyficznedlakodowaniawindows-1250
*
* Porzadek: alfabetyczny, najpierw male, potem duze
*
* @global array $PL_ARRAY_WIN_SPECIFIC
*/
$PL_ARRAY_WIN_SPECIFIC = array(
\"\xb9\", \"\x9c\", \"\x9f\",
\"\xa5\", \"\x8c\", \"\x8f\"
);
Opis niektórych funkcji zawartych w pakiecie PL jest uzupełniony przykładami użycia. Blok funkcji {stala}str_replace_arrayH(){/stala} (listing 6) zawiera przykład wywołania funkcji ujęty w znaczniki {html}
{/html} oraz {html}
{/html}.
/**
* Zamienia w napisie wszystkie wystapienia podanych napisow ich odpowiednikami
*
* Napisy do zmiany oraz ich odpowiedniki podajemy w tablicy.
*
* Tabela $ArraySubstitutions jest dwuwymiarowa pozioma. Zakladamy poprawnosc danych wejsciowych.
* Przyklad:
*
*
* @param array tablica zmian
* @param string napis, w ktorym wykonujemy zmiany
* @return string napis po dokonanych zmianach
*/
function str_replace_arrayH($ArraySubstitutions, $AStr)
{
$tmpCount = count($ArraySubstitutions);
for ($i = 0; $i < $tmpCount; $i++) {
$AStr = str_replace(
$ArraySubstitutions[$i][0],
$ArraySubstitutions[$i][1],
$AStr
);
}
return $AStr;
}
Klasa Counter
Ostatni z przykładów, klasa Counter, demonstruje dokumentowanie kodu obiektowego. Pamiętajmy, że wraz z pojawieniem się w PHP5 specyfikatorów dostępu private, protected oraz public stosowanie znaczników @access w blokach stało się zbędne. PhpDocumentator interpretuje specyfikatory dostępu:
Podobnie rzecz się ma w przypadku metod abstrakcyjnych oraz statycznych:
/**
* Przetwarzanie danych...
*
*/
abstract protected function processData();
Dokumentacja szczegółowa wewnątrz kodu
Niezależnie od użycia pakietu PhpDocumentator wewnątrz funkcji oraz metod stosuj komentarze opisujące konkretne fragmenty kodu. Do tego celu wykorzystuj komentarze jednolinijkowe:
Zwróć uwagę na pojedynczą gwiazdkę w pierwszej linijce komentarza!
Gdzie kończy się program, a zaczyna dokumentacja?
Styl programowania, w którym kod komputerowy przeplata się z wbudowaną dokumentacją, jest opisany w książce Donalda Knutha pt. \"Literate programming\". Programy pisane w systemie CWEB, zaproponowanym przez Knutha, stanowią zlepek kodu w języku C oraz dokumentacji w TeX-u. Warto zwrócić uwagę, że Knuth użył terminu WEB dekadę wcześniej, niż uczynił to Tim Berners Lee.
Powyższe komentarze nie będą brane pod uwagę przez PhpDocumentatora i nie pojawią się w wygenerowanej dokumentacji. PhpDocumentator analizuje wyłącznie komentarze będące blokami (czyli rozpoczynające się od dwóch gwiazdek w pierwszej linijce).
Podsumowanie
Aplikacja PhpDocumentator jest najlepszym rozwiązaniem w dziedzinie automatycznego generowania dokumentacji API dla bibliotek pisanych w PHP. Jest ona stosowana w wielu projektach, na czele z PEAR oraz Smarty. Szukając bardziej szczegółowych informacji na temat dokumentowania kodu PHP, warto zajrzeć do kodu źródłowego kilku przykładowych pakietów PEAR oraz Smarty. Znajdziesz tam liczne przykłady bloków dokumentacyjnych oraz znaczników stosowanych przez system PhpDocumentator.
