phpDocumentor

Školení, která pořádám

Součástí PEAR Coding Standards je i popis používání komentářů, především pro okamžitou dokumentaci kódu. Pro extrakci dokumentačních komentářů se dá použít několik nástrojů s podobnou syntaxí, v PHP je asi nejrozšířenější phpDocumentor. Dokumentační komentáře nejsou nějakou zvláštností PHP a používají se i v jiných jazycích, např. v Javě je k dispozici Javadoc.

Dokumentační komentáře doporučuji používat i v případě, kdy z nich dokumentaci vytvářet neplánujete, přeci jen to je standardní způsob, kterému by měl každý zkušenější programátor rozumět. Mohou je automaticky využívat i pokročilejší vývojová prostředí pro nápovědu k uživatelským funkcím.

Sám dokumentační komentáře používám hlavně pro stručný popis funkcí, typu a významu jejich parametrů a návratových hodnot:

<?php
/** Stručný popis funkce
* @param typ popis
* @return typ popis
*/
?>

Dokumentační komentář je uvozen posloupností /**, značky jsou uvozeny zavináčem. Značek je k dispozici samozřejmě víc, jejich kompletní přehled najdete např. v tutoriálu.

Jakub Vrána, Seznámení s oblastí, 6.1.2006, diskuse: 6 (nové: 0)

Diskuse

Michal Molhanec:

Ja pouzivam Doxygen( http://www.stack.nl/~dimitri/doxygen/index.html ), hlavne proto, ze ho pouzivam i na C++.

Jirka:

Cesky preklad tutorialu k phpDocumentoru:
http://www.kiv.zcu.cz/~brada/vyuka/files/pia/ppp/phpdoc/index.php

ikona D1ce:

Škoda, že v době čtení vašeho komentáře jsem už anglickou dokumentaci přelouskal, ale i tak díky.

ikona llook:

Za dokumentační se nepovažují řádky, které nezačínají hvězdičkou následovanou mezerou. Takže příklad by měl vypadat třeba takhle:
<?php
/** Stručný popis funkce
* @param typ $parametr popis
* @return typ popis
*/
?>

ikona Jakub Vrána OpenID:

Díky za upozornění, opravil jsem to. Některé dokumentační systémy se bez hvězdičky obejdou, phpDocumentor jasně říká, že řádky bez hvězdičky ignoruje.

Používejte diakritiku. Vstup se chápe jako čistý text, ale URL budou převedeny na odkazy a PHP kód uzavřený do <?php ?> bude zvýrazněn. Pokud máte dotaz, který nesouvisí s článkem, zkuste raději diskusi o PHP, zde se odpovědi pravděpodobně nedočkáte.

Jméno: URL: Reakce na: Jakub Vrána

Michal Molhanec:

BTW ma phpDocumentor online vyhledavani?
avatar © 2005-2019 Jakub Vrána. Publikované texty můžete přetiskovat pouze se svolením autora. Ukázky kódu smíte používat s uvedením autora a URL tohoto webu bez dalších omezení Creative Commons. Můžeme si tykat. Skripty předpokládají nastavení: magic_quotes_gpc=Off, magic_quotes_runtime=Off, error_reporting=E_ALL & ~E_NOTICE a očekávají předchozí zavolání mysql_set_charset. Skripty by měly být funkční v PHP >= 4.3 a PHP >= 5.0.