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/.
Zacznijmy może on przykładu absolutnie niepoprawnej dokumentacji, dajmy na to - pierwszej lepszej klasy z metodą liczącą pole prostokąta:
[code]
<?php
// v.1.0
class JakasKlasa {
// to jest jakas tam klasa, w pierwszej metodzie mnoży dwie liczby
public $x // tutaj publiczna właściwośc $x
private $z; // tutaj prywatna $z
public function policzPole($a, $b) {
// metoda mnoży $a i $b
$c = $a * $b;
return $c; // zwracamy $c
}
}
?>
[/code]
Totalny chaos prawda? Pomijając już nawet fakt, iż dokumentację powinniśmy pisać w języku angielskim oraz miejsca umieszczenia komentarzy, które są tutaj rozsypane po kodzie totalnie chaotycznie, to taka dokumentacja absolutnie niczego nie mówi. Nie określa w żaden sposób do czego dana klasa służy, do czego służy jej metoda (poza opisem, że pomnoży dwie zmienne). Brakuje opisu przyjmowanych przez metodę parametrów, brakuje opisu zwracanej przez metodę wartości i generalnie brakuje tutaj wszystkiego.
Spójrzmy teraz na przykład, który pokaże jak poprawnie powinien być opisany powyższy krótki kod, na razie za pomocą zwykłych komentarzy:
[code]
<?php
/*
jakasKlasa
v.1.0
Klasa służy do tego i tamtego.
*/
class JakasKlasa {
// public integer $x - wartość przechowuje to
public $x;
// private string $z - wartość przechowuje coś innego
private $z;
/*
policzPole
Metoda liczy pole prostokąta
Pobiera argumenty:
integer $a - bok A
integer $b - bok B
Zwraca:
integer $c - pole prostokąta
*/
public function policzPole($a, $b) {
$c = $a * $b;
return $c;
}
}
?>
[/code]
Powyżej to oczywiście bardzo luźny przykład, ale obrazuje on jakie informacje powinny się w dokumentacji znaleźć i jak mniej więcej dokumentacja powinna być zbudowana. Opis taki jak powyżej będzie dla innego programisty o wiele bardziej zrozumiały, niż w przypadku przykładu jaki zobaczyliśmy na początku. Dodatkowo taki opis przekazuje programiście wszystkie niezbędne informacje, takie jak rodzaj pobieranych argumentów, czy rodzaj zwracanych danych - a to programistę interesuje bardziej, niż dodana od niechcenia informacja, że oto w tym momencie zostaje zwrócona niewiadomego zastosowania zmienna $c. Programista nie potrzebuje takich abstrakcyjnych informacji, programista potrzebuje ścisłej, krótkiej, ale treściwej informacji o zastosowaniu danego elementu, o jego parametrach wejściowych i parametrach jakie zwróci.
Zobaczmy teraz jak wyglądałaby dokumentacja zrobiona w pełni poprawnie, za pomocą bloków DocBlock:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
* @version 1.0
* @author Ja
*/
/**
* Klasa udostepniajaca kilka operacji matematycznych.
*
* To jest przykladowa klasa, a to jest troche dluzszy jej opis.
* To druga linijka opisujaca klase.
*/
class JakasKlasa {
/** @var integer $x przechowuje to i tamto */
public $x;
/** @var string $z przechowuje cos innego */
private $z;
/**
* Oblicza pole prostokata
*
* Przyklad uzycia:
* $obj = new JakasKlasa;
* $result = $obj->policzPole($a, $b);
*
* @param integer $a Bok A prostokata.
* @param integer $b Bok B prostokata.
*
* @return integer $c Pole prostokata.
*/
public function policzPole($a, $b) {
$c = $a * $b;
return $c;
}
}
?>
[/code]
Powyższe w wygenerowanej przez phpDocumentator dokumentacji wyglądałoby tak:
phpDocumentator
DocBlock
Dokumentacja kodu dla phpDocumentatora umieszczana jest w specjalnych blokach przypominających komentarze blokowe o nazwie DocBlock. Bloki takie różnią się od zwykłych komentarzy tym, że rozpoczynamy je od dwóch gwiazdek występujących po slashu (/**).Zamiast jednej gwiazdki jak w przypadku zwykłego komentarza:
[code]
/*
* ...jakaś treść...
*/[/code]
W DocBlock używamy dwóch gwiazdek:
[code]
/**
* ...jakaś treść...
*/[/code]
Możemy też stosować bloki jednolinijkowe:
[code]/** ...jakaś treść... */[/code]
Aby być dokładnym, opisać musimy sobie z czego taki DocBlock się składa, a jest tutaj pewna hierarchia:
Otóż DocBlock to blok komentarza składający się z komentarza DocComment, w którym zawiera się z koleji dokumentacja PHPDoc.
PHPDoc
Nazwą PHPDoc nazywamy tą część dokumentacji, która opisuje jakąś pojedyńczą strukturę kodu, np. jakąś funkcję.
Przykładowo, zapis:
[code]
Funkcja zwraca pole prostokąta.
@return integer[/code]
jest sekcją typu PHPDoc.
DocComment
Taki PHPDoc jednak nie występuje samodzielnie w kodzie, a jest on zawsze umieszczany w bloku komentarza typu DocComment. Komentarz takiego typu różni się od zwykłego komentarza tym, że zaczyna się od slasha i dwóch gwiazdek (/**), a także tym, że każda linijka musi zaczynać się od gwiazdki, a więc np.:
[code]
/**
*
*
*
*/[/code]
Wszystkie gwiazdki powinny być ponadto wyrównane w pionie do pierwszej gwiazdki występującej po początkowym slashu.
I teraz dopiero sekcję PHPDoc ubraną w komentarz typu DocComment nazywamy poprawnie DocBlockiem.
To tak absolutnie na marginesie, abyśmy wiedzieli, czym różnią się te 3 pojęcia.
UWAGA: Bardzo ważne, abyśmy pamiętali o następującym - dokumentację najlepiej jeśli robimy w języku angielskim, jeśli jednak uparliśmy się na język polski to pamiętajmy o kluczowej sprawie: nie używamy w dokumentacji ŻADNYCH polskich znaków. Użycie jakichkolwiek znaków poza standardowym angielskim alfabetem (nieważne, czy to polskie ogonki, czy chińskie szlaczki) spowoduje problemy podczas generowania dokumentacji. Należy o tym pamiętać!
Blok główny - @package
Musimy na początek wiedzieć, iż za pomocą DocBlocków dokumentujemy elementy kodu występujące bezpośrednio po bloku komentarza. Co za tym idzie, zapis taki:[code]
/**
* to jest DocBlock
*/
define('MY_CONST', true);
class MyClass {
}[/code]
dotyczy jedynie stałej przed którą występuje, nie dotyczy natomiast w żaden sposób klasy tóż po niej.
Aby opisać klasę, musimy dodać kolejny blok:
[code]
/**
* to jest DocBlock
*/
define('MY_CONST', true);
/**
* to jest DocBlock dla klasy
*/
class MyClass {
}[/code]
Drugą kluczową sprawą jest to, iż dokumentowanie takie dotyczy opisu API, a nie poszczególnych segmentów występujących w kodzie. Nie stosujemy DocBlocków do opisywania pętli, czy innych operacji.
Za pomocą DocBlocka dokumentujemy jedynie elementy takie jak:
- Zmienne globalne
- Stałe
- Funkcje
- Instrukcje
- Klasy
- Interfejsy
- Stałe klas
- Własności klas
- Metody klas
Nie stosujemy DocBlocków do opisu fragmentów funkcji, czy pętli - nie służą one do tego. Dokumentowany element musi znaleźć się zaraz po bloku komentarza (nie dajemy pomiędzy nimi pustej linijki).
Trzecia kluczowa sprawa - każdy plik z kodem musi posiadać blok główny, który umieszczamy na samym początku i który dotyczy całego dokumentu/pliku.
Blok główny możemy dodać na dwa sposoby, należy bowiem zauważyć, iż zapis np. taki:
[code]
<?php
/**
* to jest DocBlock
*/
class MyClass {
}
?>[/code]
wcale nie oznacza, iż zamieszczony tutaj blok jest blokiem głównym. Akurat w tym przypadku dotyczy on klasy, nawet pomimo tego, iż występuje on tutaj na samym początku pliku.
Aby dodać blok główny, musimy albo zamieścić jeszcze jeden blok, którym poprzedzimy blok występujący dla klasy, albo zawrzeć w nim tag o nazwie:
[code]@package[/code]
Pierwszym sposobem zrobimy to tak:
[code]
<?php
/**
* to jest DocBlock główny
*/
/**
* to jest DocBlock dla klasy
*/
class MyClass {
}
?>[/code]
Natomiast sposobem drugim zrobimy to tak:
[code]
<?php
/**
* to jest DocBlock główny
* @package MojaAplikacja
*/
class MyClass {
}
?>[/code]
W tym drugim przypadku, tag @package określa, iż mamy tutaj do czynienia z blokiem głównym, a nie z blokiem opisującym jakąś strukturę.
Tag @package służy do wydzielenia danego logicznego bloku dla aplikacji. Gdy jest ona określana na początku pliku to obowiązuje ona dla całości tego pliku, jeśli jest zadeklarowana dla przestrzeni nazw to obowiązuje dla danej przestrzeni nazw. Mówiąc prostrzym językiem - pozwala na zgrupowanie większej ilości struktur w jakąś logiczną całość. W jednym bloku PHPDoc może znaleźć się tylko jedna definicja dla @package.
Ogólna składnia
Wszystkie elementy opisujemy w DocBlockach w pewnien określony sposób wg określonej składni.Każdy taki blok powinien wyglądać następująco:
[code]
/**
* Opis skrócony.
*
* Opis długi.
* Opis długi.
* [...]
*
* @tag
* @tag
* [...]
*/[/code]
Opis krótki powinien tutaj w sposób zwięzły określać do czego służy opisywany element. Powinien być prosty i w skrócony sposób informować do czego dany element służy. Musi zamknąć się w jednej linijce. Opis długi natomiast to bardziej rozbudowany opis, może on zawierać dowolną liczbę linijek - w opisie długim możemy np. opisać daną klasę dokładniej, podać przykłać jej użycia itd.
Przykładowo:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
* Przyklad uzycia:
* $pole = Klasa::obliczPole($a, $b);
* [...]
*/
public static function obliczPole($a, $b)
{
// kod metody
}[/code]
W opisie długim możemy używać następujących tagów HTML: <br>, <b>, <i>, <ol>, <ul>, <li>, <pre>, <code>, <kbd>, <samp>, <var>.
Opis długi może zostać pominięty, opis krótki powinien być podany zawsze.
Przykład użycia tagów HTML:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
* <b>Przyklad uzycia:</b>
* <pre>$pole = Klasa::obliczPole($a, $b);</pre>
* [...]
*/[/code]
Uwaga: do zacytowania fragmentu z tagami HTML (np. gdy chcemy podać w przykładzie tag HTML, ale jako zwykły tekst) stosujemy podwójne znaki << oraz >>:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
* <<b>>To nie zostanie pogrubione, tag b zostanie wyświetlony jako tekst.<</b>>
* [...]
*/[/code]
Opis danych wejściowych i zwracanych - @param i @return
Przy opisie metod i funkcji powinniśmy zawsze podawać opis przyjmowanych argumentów oraz opis wartości przez funkcję lub metodę zwracanych. Do opisu przyjmowanych parametrów służy tag o nazwie:[code]@param[/code]
Składnia użycia wygląda następująco:
[code]@param typ $nazwa Opis.[/code]
Przykład użycia tagu @param przedstawiam poniżej:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
* Przyklad uzycia:
* $pole = Klasa::obliczPole($a, $b);
*
* @param integer $a Bok A prostokata.
* @param integer $b Bok B prostokata.
*/
public static function obliczPole($a, $b)
{
// kod metody
}[/code]
Opis wartości zwracanej przez funkcję, lub metodę opisujemy za pomocą taga:
[code]@return[/code]
Składnia wygląda podobnie jak przy @param, ale tutaj nie podajemy już nazwy zwracanego elementu (bo takowy zawsze jest tylko jeden):
[code]@return typ Opis.[/code]
Przykład użycia poniżej:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
* Przyklad uzycia:
* $pole = Klasa::obliczPole($a, $b);
*
* @param integer $a Bok A prostokata
* @param integer $b Bok B prostokata.
*
* @return integer Pole prostokata.
*/
public static function obliczPole($a, $b)
{
$c = $a * $b;
return $c;
}[/code]
Jeśli funkcja, lub metoda może zwrócić różne typy, np. NULL w przypadku wystąpienia danego zdarzenia, to również opisujemy taką możliwość na zasadzie:
[code]@return integer|null Pole prostokata.[/code]
Zmienne i własności - @var
Pojedyńcze elementy jak zmienne, czy własności klasy dokumentujemy w jednej linijce za pomocą taga:[code]@var[/code]
gdzie składnia wygląda następująco:
[code]@var typ $nazwa Opis[/code]
Przykład użycia poniżej:
[code]/** @var string $email Adres email uzytkownika */
protected $email;[/code]
Przy opisie elementu, który jest tablicą dodajemy zawsze nawiasy kwadratowe po typie, np.:
[code]/** @var string[] $owoce Tablica z owocami */
protected $owoce;[/code]
Tagi opisujące
W dokumentacji możemy, a nawet powinniśmy podać oczywiście takie dane jak nazwa autora kodu, licencja, wersja, czy link do strony projektu.@link
Aby dodać link do dokumentacji, używamy taga:[code]@link <URI> Opis.[/code]
Przykład:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
*
* @link http://www.projekt.com Strona glowna projektu.
*/
[...][/code]
Opis linku nie jest wymagany.
@author
Aby dodać autora kodu do dokumentacji używamy:[code]@author nazwa_autora[/code]
Przykład:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
*
* @link http://www.projekt.com Strona glowna projektu.
* @author Jan Kowalski
*/
[...][/code]
@license
Aby dodać licencję, na której udostępniamy projekt, wykorzystujemy tag:[code]@license <URI> nazwa_licencji[/code]
Przykład:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
*
* @link http://www.projekt.com Strona glowna projektu.
* @author Jan Kowalski
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*/
[...][/code]
Adres URI nie jest wymagany.
@version
Aby dodać numer wersji projektu, lub elementu, korzystamy z taga:[code]@version numer_wersji[/code]
Przykład:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
*
* @link http://www.projekt.com Strona glowna projektu.
* @author Jan Kowalski
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version 1.0.0
*/
[...][/code]
@copyright
Aby dodać informację o prawach autorskich, korzystamy z taga:[code]@copyright Opis.[/code]
Przykład:
[code]
<?php
/**
* MySuperApp
*
* @package MySuperApp
*
* @link http://www.projekt.com Strona glowna projektu.
* @author Jan Kowalski
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version 1.0.0
* @copyright 1999-2015 Jan Kowalski
*/
[...][/code]
@example
Możemy podać adres do zewnętrznego przykładu, który np. demonstruje działanie danego elementu.[code]@example <url> <linijka_startowa> <ilość linijek> Opis.[/code]
Przykładowo, jeśli chcemy podać odnośnik do pliku example1.php, gdzie przykład użycia znajduje się w linijkach od 5 do 12, podajemy:
[code]@example example1.php 5 7 Tu znajdziesz opis dzialania.[/code]
Numer i ilość linijek w kodzie nie jest wymagany.
Jako <url> można podać ścieżkę bezwzględną, albo relatywną, oba poniższe przykłady będą poprawne:
[code]
/**
* @example example1.php 5 7 Tu znajdziesz opis dzialania.
* @example http://www.projekt.com/example1.php Tu znajdziesz opis dzialania.
*/[/code]
@see
Możemy odwołać się do adresu URI, lub do innego elementu w kodzie, aby podac np. jakiś przykład działania. Można to przyrównać do zobacz też: .... Podajemy albo adres do pliku, albo nazwę elementu w kodzie.Składnia wygląda następująco:
[code]@see URI|element Opis.[/code]
Przykłady użycia:
[code]
/**
* @see http://projekt.com/doc/example Dokumentacja.
* @see MyClass::$blabla W tej wlasnosci trzymamy xyz.
* @see MyClass::otherClass() Inne dzialanie.
*/[/code]
@uses
Tag określa powiązanie z inną opisywaną strukturą. Działa podobnie do @see, ale w obie strony.Powiązanie takie zostanie uwzględnione po obu stronach.
Składnia wyglada tak:
[code]@uses nazwa Opis.[/code]
Przykład użycia:
[code]
/**
* @uses MyClass::$blabla W tej wlasnosci trzymamy xyz.
*/[/code]
@throws
Tag ten pozwala na opisanie rzucanych przez metodę lub funkcję wyjątków.Składnia użycia:
[code]@throws typ opis.[/code]
Przykład użycia:
[code]
/**
* Metoda zwraca pole prostokata.
*
* Oblicza pole prostokata na podstawie zadanych parametrow.
*
* @throws InvalidArgumentException jesli podane parametry nie sa typu integer.
*/
public static function obliczPole($a, $b)
{
// kod
}[/code]
@deprecated
Pozwala określić, czy i od kiedy dany element jest już przestarzały.Składnia użycia taga wygląda tak:
[code]@deprecated wersja opis.[/code]
Przykłady użycia:
[code]
/**
* @deprecated
* @deprecated 1.0.2
* @deprecated Metoda nie jest juz uzywana.
* @deprecated 1.0.2 Nie jest juz uzywana, nie radzimy korzystac, zamiast tego uzyj xyz().
*/
public static function obliczPole($a, $b)
{
// kod
}[/code]
@since
Określa od której wersji dany element jest używany.Składnia wygląda tak:
[code]@since wersja Opis.[/code]
Przykłady użycia:
[code]
/**
* @since 1.2
* @since 1.2 Pierwszy raz wystapila w kodzie
* @since 1.3 Dodano dodatkowy argument $c
*/
public static function obliczPole($a, $b, $c)
{
// kod
}[/code]
@todo
Pozwala opisać, co jeszcze do zrobienia zostało w opisywanym elemencie.Możemy np. dopisać co planujemy jeszcze zrobić z daną metodą.
Składnia użycia:
[code]@todo Opis.[/code]
Przykład:
[code]
/**
* Metoda zwraca pole prostokata.
*
* @todo Zrobic sprawdzenie typu parametrow $a i $b
*/
public static function obliczPole($a, $b)
{
// kod
}[/code]
@ignore
Dodanie tego taga spowoduje, że oznaczony nim element nie będzie uwzględniony w dokumentacji sporządzanej przez phpDocumentatora.Składnia:
[code]@ingore Opis.[/code]
gdzie opis jest opcjonalny.
Przykład użycia:
[code]
/**
* Metoda zwraca pole prostokata.
*
* @ignore Metoda obliczPole() nie zostanie umieszczona w dokumentacji
*/
public static function obliczPole($a, $b)
{
// kod
}[/code]
@internal
Tagiem tym oznaczamy wewnętrzne, kluczowe elementy aplikacji. Możemy go użyć do zaznaczenia faktu, że dokumentowana struktura należy do wewnętrznego kodu i nie powinna być w żaden sposób modyfikowana.Składnia:
[code]@internal Opis.[/code]
lub w formie jednolinijkowej:
[code]{@internal Opis.}}[/code]
(zauważmy, że na końcu są dwa nawiasy)
@filesource
Pozwala na dołaczenie do dokumentacji tworzonej przez phpDocumentator kodu źródłowego obecnego pliku. Będzie on wtedy dostępny po wybraniu odpowiedniej opcji podczas czytania sporządzonej dokumentacji.Składnia użycia wygląda bardzo prosto:
[code]
/**
* @filesource
*/[/code]
@category
Tag ten pozwala na grupowanie bloków @package w określone, logiczne kategorie. Chcą np. podzielić naszą aplikację na jakieś logicznie ze sobą związane elementy, używamy taga @category.Składnia użycia:
[code]@category Opis.[/code]
Przykład użycia:
[code]
/**
* Klasa obsluguje dodawanie uzytkownikow
*
* @category Users
* @package NewUsers
*/[/code]
@inheritDoc
Powoduje skopiowanie bloku dokumentacji z klasy bazowej lub interfejsu. Użycie tego taga np. w opisie klasy dziedziczącej po klasie bazowej spowoduje dodanie w tym miejscu opisu klasy bazowej, z której dziedziczymy.Składnia użycia:
[code]{@inheritdoc}[/code]
Przykład:
[code]
/**
* Klasa bazowa
*
* Opis klasy bazowej
*/
interface MyInterface {
/**
* Opis metody, ktory zostanie pozniej skopiowany i zalaczony do klasy implementujacej
*/
public function MyMethod();
}
class MyClass implements MyInterface {
/**
* {@inheritDoc}
*/
public function MyMethod() {
// kod
}
}[/code]
Spowoduje skopiowanie bloku dokumentacji z interfejsu.
@method
Tag ten pozwala na określenie jakie metody mogą być wywołane w klasie za pomocą __call(). Warunkiem jest użycie metody __call() w opisywanej klasie, lub klasie rodzica. Określa ponadto typ zwracanych danych.Składnia wygląda następująco:
[code]@method zwracany_typ nazwa_metody(typ parametr1, ....) Opis.[/code]
Przykład użycia:
[code]
class ParentClass
{
public function __call()
{
// kod
}
}
/**
* @method void setInteger(integer $integer) Jakis opis.
*/
class ChildClass extends ParentClass
{
// kod
}[/code]
@property
Tag podobny do powyższego, ale dotyczy własności klasy. Określa jakie magiczne własności mogą być użyte.Składnia wygląda następująco:
[code]@property typ $nazwa opis[/code]
Przykład użycia:
[code]
class ParentClass
{
public function __get()
{
// kod
}
}
/**
* @property string $jakasWlasnosc Jakis opis.
*/
class ChildClass extends ParentClass
{
// kod
}[/code]
Analogicznie działają tagi:
[code]@property-read[/code]
który określa własności, które mogą być jedynie odczytywane, np.:
[code]
class ParentClass
{
public function __get()
{
// kod
}
}
/**
* @property-read string $jakasWlasnosc Jakis opis.
*/
class ChildClass extends ParentClass
{
// kod
}[/code]
oraz
[code]@property-write[/code]
który określa własności, które mogą być zapisywane, np.:
[code]
class ParentClass
{
public function __set()
{
// kod
}
}
/**
* @property-read string $jakasWlasnosc Jakis opis.
*/
class ChildClass extends ParentClass
{
// kod
}[/code]
Typy elementów
Warto wiedzieć, że dane elementy opisywać można również za pomocą znaczników takich jak:[code]@abstract[/code]
[code]@global[/code]
[code]@access private|public|protected[/code]
[code]@final[/code]
[code]@static[/code]
[code]@staticvar[/code]
np.
[code]
/**
* Metoda zwraca pole prostokata.
*
* @final
* @static
*/
public final static function obliczPole($a, $b)
{
// kod
}[/code]
To tyle jeśli chodzi o opis tagów używanych do dokumentowania struktur kodu.
phpDocumentator
Nauczyliśmy się w jaki sposób kod powinien zostać opisywany, czas teraz na przykładowe wygenerowanie dokumentacji za pomocą phpDocumentatora. Bibliotekę możemy pobrać ze strony: http://phpdoc.org/. Istnieje kilka sposobów instalacji, my wykorzystamy Composera.Stwórzmy jakiś katalog, np.
[code]/www/phpdoc/[/code]
i utwórzmy w nim plik composer.json
o treści:
[code]
{
"require-dev": {
"phpdocumentor/phpdocumentor": "2.*"
}
}[/code]
Następnie pobierzmy całość za pomocą Composera:
[code]
$ cd phpdoc
$ composer install[/code]
Pobierze nam to cały pakiet, a w katalogu:
[code]/vendor/bin[/code]
umieści nam narzędzia konsolowe służące do sporządzania dokumentacji.
Skopiujmy teraz jakiś utworzony przez nas i udokumentowany za pomocą DocBlock kod i umieśćmy go w folderze np.:
[code]/www/phpdoc/src[/code]
Następnie w konsoli skorzystajmy z narzędzia phpdoc:
[code]$ "vendor/bin/phpdoc.bat" -d ./src -t ./docs[/code]
w Windowsie, lub na Linuxach:
[code]$ vendor/bin/phpdoc -d ./src -t ./docs[/code]
Wywołanie phpdoc z parametrem -d:
[code]phpdoc -d /sciezka/do/folderu[/code]
generuje dokumentację dla zadanego folderu
Wywołanie z parametrem -f:
[code]phpdoc -f nazwa_pliku[/code]
Tworzy dokumentację tylko dla zadanego pliku
Parametr -t:
[code]phpdoc -t /sciezka/do/dokumentacji[/code]
określa katalog, do którego ma być wygenerowana dokumentacja.
Wygenerujmy wiec sobie przykładową dokumentację i zobaczmy na wynik, który zobaczymy w folderze /docs.
Przykładowo:
Opis pełnej konfiguracji jeśli chodzi o generowanie dokumentacji znajdziemy pod adresem: http://phpdoc.org/docs/latest/references/configuration.html
Opis zmiany szablonów dla generowanej dokumentacji natomiast tutaj: http://phpdoc.org/docs/latest/getting-started/changing-the-look-and-feel.html
Na chwilę obecną umiemy już poprawnie dokumentować kod, co za tym idzie również i praca z phpDocumentatorem nie sprawi nam żadnych problemów.
W następnej części nauczymy się konfiguracji i zmiany wyglądu generowanej dokumentacji na przykładach.
Dzięki ;)
OdpowiedzUsuńkuşadası transfer
OdpowiedzUsuńfoça transfer
alaçatı transfer
didim transfer
karşıyaka transfer
A1UF