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.
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
D1ce:
Škoda, že v době čtení vašeho komentáře jsem už anglickou dokumentaci přelouskal, ale i tak díky.
D1ce: 
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
*/
?>
llook: 
Jakub Vrána 
:
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.
Jakub Vrána : Michal Molhanec:
BTW ma phpDocumentor online vyhledavani?Diskuse je zrušena z důvodu spamu.
© 2005-2024 