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.