XMind

phpDocumentor

1. Základní tagy

   1. začínají na @ a píší se na konec DocBloku

   2. @abstract

      nějaká metoda či třída abstraktní => i třída se musí se musí explicitně označit

      1. označit lze: třídu, atribut, metodu

      2. parametry: popis

   3. @access

      pokud použijeme private, tak nebude v dokumentaci => pouze tehdy, pokud použijeme parametr --parseprivate nebo -pp docílíme různých typů dokumentací (pro uživatele a vývojáře)

      1. označit lze: cokoliv

      2. parametry: public/private (bez -pp neni v dokumentaci)/protected

   4. @author

      1. označit lze: cokoliv

      2. parametry: jméno

   5. @copyright

      1. označit lze: cokoliv

      2. dědí se od rodičovské třídy

   6. @deprecated

      1. označit lze: cokoliv kromě souboru

      2. parametry: informace

      3. význam: označuje zastaralé elementy, které se nedoporučují používat

   7. @example

      1. označit lze: soubor

      2. význam: označuje soubor s příkladem

   8. @final

      1. označit lze: metody a třídy

      2. význam: takto označené metody by se neměly překrývat v děděných třídách

   9. @filesource

      pokud chceme zdrojový text ke každému souboru, použijeme parametr -s nebo --sourcecode

      1. označit lze: soubor

      2. význam: pokud se tag objeví v prvním DocBloku souboru, k dokumentaci v tomto souboru se přidá zdrojový text

   10. @ignore

       1. označit lze: cokoliv

       2. význam: nebude se dokumentovat

   11. @internal

       1. označit lze: cokoliv

       2. význam: poznámky, nebudou se dokumentovat

   12. @license

       1. označit lze: cokoliv

       2. parametry: URL popis

   13. @link

       1. označit lze: cokoliv

       2. parametry: URL popis

       3. význam: odkaz na stránku, e-mail apod.

   14. @package

       pokud nebude označen soubor, bude v balíku default pokud nebude označena třída, nebude zařazena v žádném balíku písmena, čísla, znaky _ - [ ] case sensitive

       1. označit lze: soubory a třídy

       2. parametry: název

       3. význam: řazení souborů a tříd do balíků pro lepší přehled

   15. @param

       1. označit lze: funkce a metody

       2. parametry: datový_typ $proměnná popis

       3. význam: dokumentování paramentrů funkce, když nemá proměnná typ, uvede se mixed

   16. @return

       1. označit lze: funkce a metody

       2. parametry: datový_typ popis

       3. význam: návratová hodnota fce, pokud neznáme, použijeme mixed

   17. @see

       * @see jadro.php, HlavniOkno, Dialog::spust(), $width * @see PHP_MANUAL#get_class

       1. označit lze: cokoliv

       2. parametry: odkaz, odkaz, odkaz, ...

       3. význam: odkazování na jakýkoliv popisovaný element v dokumentaci kromě include a require, $proměnná - odkaz na proměnnou ve stejné třídě, fce(), třída, třída::atribut, třída::metoda(), soubor.přípona - soubor se musí dokumentovat

       4. POMOCÍ PHP_MANUAL#element přímo na webové stránky php s popisem elementu

   18. @since

       1. označit lze: cokoliv

       2. parametry: verze/informace

       3. význam: dokumentuje verzi souftware, od které je popisovaný element jeho součástí

   19. @static

       1. označit lze: třídy a metody

       2. parametry: poznámky

       3. význam: takto označené metody je možné volat přímo bez nutnosti vytvářet instance třídy

   20. @staticvar

       1. označit lze: funkce a metody

       2. parametry: datový_typ popis

       3. význam: pro fce mající deklarovány statické proměnné (jejichž hodnota se udržuje při celém běhu skriptu)

   21. @subpackage

       1. označit lze: soubory a třídy

       2. parametry: název

       3. význam: smysl pouze s tagem package, více subbalíků pak sdruženo do 1 balíku

   22. @todo

       1. označit lze: cokoliv

       2. parametry: poznámky

       3. význam: poznámka bude vypsána ve zvláštní sekci dokumentu

   23. @uses

       1. označit lze: cokoliv

       2. parametry: odkaz popis_použití

       3. význam: vytvoří odkaz i zpětný odkaz na element, který je v popisovaném nějak použit

   24. @var

       1. označit lze: atributy třídy

       2. parametry: datový_typ popis

       3. význam: popis atributu třídy, každý DocBlok může mít maximálně jeden tento tag

   25. @version

       1. označit lze: cokoliv

       2. parametry: verze

       3. význam: verze elementu, dědí se od rodičovské třídy

2. Inline tagy

   1. ve tvaru {@tag neco} se pisi primo do kratkeho nebo dlouheho popisu v DocBloku

   2. {@internal}}

      1. označit lze: cokoliv

      2. parametry: popis

      3. význam: nebude vidět v dokumentaci, pouze s -pp, musi koncit 2 složenými závorkami

   3. {@inheritdoc}

      1. označit lze: odděděné třídy

      2. význam: u třídy potomka bude nahrazen jeho dlouhým popisem rodičovské třídy, musí být umístěn ve dlouhém popisu, automaticky se dědí autor, copyright, licence

   4. {@link}

      1. označit lze: cokoliv

      2. parametry: url popis / element popis

      3. význam: kdekoliv v DocBloku uvést odkaz na element z dokumentace nebo URL

   5. {@source}

      1. označit lze: funkce a metody

      2. parametry: 1.řádek počet_řádků

      3. význam: je nahrazen výpisem zdrojáku popisované fce, bez parametrů se vypíše celá

3. Základy

   1. nástroj, kterým automaticky vytváří dokumentaci php programu z komentářů

   2. DocBlok

      1. /** * kratky popis * * dlouhy popis */

         1. Krátký popis končí buď za větou nebo prázdnou řádkou, max na 3 řádky, pokud delší bere se pouze 1. a zbytek se považuje za dlouhý popis

         2. Dlouhý popis je libovolně dlouhý, nepovinný, na konci může být seznam tagů, může obsahovat odstavce (prázdné řádky nebo přímo

            )

   3. HTML tagy v DocBloku

      1. , ,
,

      2. - vstup z klávesnice/výpis na obrazovce

      3. ,
         ,
         1. ,

      4.  - ponechává všechny bílé znaky

      5. - příklad nebo vzor

      6. - název proměnné

   4. Řídící značky jako text

      1. => <>

      2. */ => {@*}

   5. Seznamy

      1. /** * necislovany seznam * - prvni * - druhy */

         1. lze použít -, + nebo #

      2. /** * cislovany seznam * 1. prvni * 2. druhy */

      1. nelze použít vnořování seznamů

   6. Šablony

      1. pro opakující se texty (hlavně pro tagy), vychozí hodnoty v šabloně se mohou přepisovat

      2. začátek

         1. /**#@+ * opakující se text */

      3. konec

         1. /**#@-*/