phpDocumentor

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++.
6.1.2006 01:36:07

ikona D1ce:

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

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
*/
?>
6.1.2006 12:19:14

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.
6.1.2006 12:53:46

Michal Molhanec:

BTW ma phpDocumentor online vyhledavani?
8.1.2006 20:23:54

Diskuse je zrušena z důvodu spamu.

avatar © 2005-2025 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.