PHP

Kurz PHP (25.)

Úvodem  |  Kurz PHP |  Odkazy  |  Aplikace  |  Otázky a odpovědi

 

Dokumentování PHP kódu

V dnešním díle se budeme věnovat jedné z částí tvorby aplikací v PHP, kterou je dokumentování kódu. Jak jsme si již uváděli dříve, tak každý kód, který vytvoříme by měl být zdokumentován. Tímto krokem si zajistíme to, že pokud se ke kódu vrátíme po určité době, tak nám dané konstrukce nebudou připadat tak neznámé. Mezi další důvody patří také to, že pokud budeme chtít předat kód i dalším lidem, nebude pro ně jeho pochopení tak složité. Jako způsob dokumentace se využívá převážně integrovaných komentářů v PHP (// a /**/) nebo externích programů, jenž mají tvorbu dokumentace na starosti. My si v dnešním díle jeden z nástrojů, konkrétně nástroj phpDocumentor ukážeme a vysvětlíme s práci s ním.

Nástroj phpDocumentor je možné stáhnout ze stránek http://www.phpdoc.org, kde je možné najít také novinky o tomto nástroji a jiné podrobnosti. Pomocí tohoto nástroje můžeme vytvořit komplexní dokumentaci pokrývající všechny části zdrojového kódu. Ať již se jedná o funkce, třídy, metody, pole atd. Tento nástroj umožňuje generování dokumentace do různých formátů jako HTML (několik různých variant), PDF, CHM a XML (DocBook). Pro představu, jak může vygenerovaná dokumentace vypadat můžeme navštívit webovou adresu http://phphtmllib.newsblob.com/javadoc.php.

Instalaci tohoto nástroje ve verzi 1.3.0 RC3 můžeme provést po stažení z domovské stránky nebo zde z CD. Pro generovaní dokumentace můžeme využít několik rozhraní. Tím prvním a asi nejzajímavějším je webové rozhraní, které je přístupné po rozbalení hlavního archivu. Využívat jej můžeme například po rozbalení archivu do složky doc v rootu webového serveru http://localhost/doc/index.html (nebo samozřejmě kdekoliv jinde). Mezi další rozhraní patří využití příkazové řádky. My se v tomto díle budeme věnovat webovému rozhraní, které je jednodušší a rychlejší.

K dokumentování nejen funkcí se využívá následující blok:


1.    /**
2.    *
3.    *
4.    */

Tento blok se skládá z úvodního /** a koncového */. Každý řádek, který bude využíván k dokumentování musí začínat hvězdičkou, být umístěn na samostatném řádku a musí být samozřejmě umístěn mezi počáteční a koncovou značkou. Jako příklad si ukážeme zdokumentovaní funkce Ahoj():



/**
* toto je krátký popis pro nejlepší funkci na světě
*/
function Ahoj()
{
}

phpDocumentor rozpoznává dva druhy bloků. Tím prvním je blok, jehož popis začíná na prvním řádku a nazývá se krátký popis. Krátký popis může být ukončen tečkou nebo prázdným řádkem a je zobrazen v jednom řádku. Tím druhým je dlouhý popis, jenž se využívá k podrobnějšímu popsání činnosti zvoleného kódu.



/**
* toto je krátký popis pro nejlepší funkci na světě
*
* Toto je dlouhý popis popisující činnost této funkce
* včetně všech jejich možností atd.
*/
function Ahoj()
{
	return "Jak se máš?";
}

Dlouhý popis můžeme také formátovat pomocí několika tagů, kterými jsou:

  • <b>
  • <code>
  • <br>
  • <i>
  • <kbd>
  • <li>
  • <ol>
  • <p>
  • <pre>
  • <samp>
  • <ul>
  • <var>


/**
* toto je krátký popis pro nejlepší funkci na světě
*
* Toto je dlouhý popis popisující činnost této funkce
* včetně všech jejich možností atd.
* 
* <b>Nyní</b> si ukážeme způsob zavolání funkce.
* <code><?php echo Ahoj(); ?></code>
*/
function Ahoj()
{
	return "Jak se máš?";
}

Nyní je na čase si ukázat seznam tagů, které můžeme využívat ke specifikaci kódu. Všechny tagy začínají znakem @. Tag, který parser nerozpozná nebude zpracován. Všechny tagy, které mají být zpracovány musejí být umístěny jako první znak na nové řádce. Jako příklad si ukážeme tag @author:


/**
* Ukázka tagů
* @author Josef Novák (josef@novák.cz)
*/

Můžeme také využít vkládání tagů jakým je například tag @link (tento tag je považován za tzv. inline tag):



/**
* Ukázka inline tagů
*
* Tato funkce je velmi podobná funkci {@link Hello()}
*/
function Ahoj()
{
	return "Jak se máš?";
}
function Hello()
{
	return "How are you?";
}

Výsledkem bude odkaz na popis funkce Hello: Tato funkce je velmi podobná funkci Hello().

Nyní si ukážeme seznam všech tagů a vysvětlíme si jejich účel:

  • @abstract - Definuje zvolenou metodu, třídu nebo členskou proměnnou jako abstraktní. Tento tag funguje pouze v PHP verze 4, protože PHP 5 obsahuje klíčové slovo abstract.
  • @access - umožňuje nastavit zvolenou metodu jako private, public a protected. Pokud bude nastaveno na private, tak nebude zvolený element zdokumentován.
  • @author - slouží k uložení autora. E-mail bude zobrazen jako odkaz pokud jej umístíme mezi znaky < a >.
  • @category - slouží k uspořádání do skupin.
  • @copyright - využívá se k uložení copyrightu.
  • @deprecated - slouží k nastavení zvoleného elementu jako nevyužívaný.
  • @example - slouží ke zpracování uvedeného souboru pro zvýraznění syntaxe a vložení k dokumentaci.
  • @final - slouží k označení metody, která nemůže být přepsána. PHP 5 opět obsahuje klíčové slovo final.
  • @filesource - slouží ke zpracování kódu dokumentu, zvýraznění syntaxe, očíslování řádků a ke zahrnutí do dokumentace.
  • @global - slouží k deklaraci globální proměnné.
  • @ignore - pomocí tohoto tagu můžeme zvolený element vyřadit z dokumentování.
  • @internal - informace, která nebude zobrazena ve veřejné dokumentaci.
  • @licence - slouží k uvedení druhu licence. Dosazuje se celá URL.
  • @link - slouží k vytvoření odkazu. Dosazuje se celá URL.
  • @name - využívá se spolu s @global při tvorbě dokumentace.
  • @package - slouží k logickému seskupení elementů.
  • @param - slouží k dokumentaci parametrů funkcí. Dosazuje se typ proměnné, název a je možné dosadit i popis.
  • @return - slouží k dokumentaci návratové hodnoty funkce.
  • @see - slouží k odkazování v dokumentaci.
  • @since - slouží k dokumentování změny.
  • @static - umožňuje nastavit zvolený element jako statický.
  • @staticvar - slouží k dokumentaci statické proměnné.
  • @subpackage - umožňuje vytvořit pod kategorii vytvořenou pomocí @package.
  • @todo - slouží k vytvoření poznámky, co má být vytvořeno.
  • @tutorial - odkaz na pkg soubor s tutoriálem.
  • @uses - velmi podobné tagu @see, ale vytvoří zpáteční odkaz.
  • @var - umožňuje zdokumentovat typ a popis proměnné.
  • @version - umožňuje specifikovat verzi daného elementu.

Podrobný popis včetně rozsáhlých příkladů je možné získat na stránkách s manuálem.

Mezi poslední fáze generování dokumentace je nastavení několika voleb webového rozhraní a následné vygenerovaní.


Klikněte pro zvětšení

Webové rozhraní je rozděleno do několika sekcí:

  • Introduction - úvodní informace a novinky o tomto nástroji.
  • Config - v této sekci můžeme vybrat zvolený konfigurační soubor, pomocí kterého se řídí proces tvorby dokumentace. Konfigurační soubory se umísťují do složky user v rootu webu.
  • Files - v této sekci nalezneme:
    • Files to parse - čárkami oddělený seznam souborů, které budou zpracovány parserem při tvorbě dokumentace.
    • Directory to parse - čárkami oddělený seznam složek, které budou zpracovány parserem při tvorbě dokumentace. Pod složky jsou automaticky zpracovány.
    • Files to ignore - seznam souborů, které budou ignorovány. Je možné využívat zástupných znaků * a ?.
    • Packages to parse - seznam balíků, které budou zpracovány.
  • Output - v této sekci můžeme nastavit druh generovaného dokumentu (Output Format) a složku, do které budou výsledné soubory vygenerovány (Target).
  • Options - všeobecná nastavení pro generování dokumentace.
  • Working Directory - nakonec je potřeba nastavit adresář, se kterým se pracuje (do něhož se generuje dokumentace).

Podrobný popis všech možností tohoto nástroje je možné získat na http://www.phpdoc.org/manual.php.

Pro tento díl to bude vše. V příštím díle budeme dále pokračovat v poznávání jazyka PHP.

 
Petr Rympler