PHPDoc

Aktuální verze stránky ještě nebyla zkontrolována zkušenými přispěvateli a může se výrazně lišit od verze recenzované 28. srpna 2019; kontroly vyžadují 5 úprav .

PHPDoc  je upravený dokumentační standard Javadoc pro použití v PHP .

Popis

Standard pro komentáře má sice pouze formální status, ale plánuje se jeho konsolidace jako jeden z vývojových standardů pro frameworky PHP vyvíjené skupinou PHP-FIG. Připravovaná norma dostane číslo PSR-5 [1] . PHPDoc podporuje jak objektově orientovaný , tak procedurální kód v dokumentech.

Pro interpretaci kódu byl vytvořen samostatný program phpDocumentor .

phpDocumentor je aplikace schopná analyzovat zdrojový kód PHP a komentáře DocBlock za účelem generování kompletní sady dokumentace API [2] .

Komponenty PHPDoc

Bloky dokumentů

Doc-blocks ( angl.  DocBlock comments ) jsou víceřádkové komentáře ve stylu jazyka C umístěné před dokumentovaným prvkem. První znak v komentáři (a na začátku řádků komentáře) musí být * . Bloky jsou odděleny prázdnými řádky.

Příklad bloku Doc pro funkci foo():

/** * @param string $msg řetězec na výstup * @author WikiEditor * @copyright 2016 Wikipedia * @return string nezměněn */ function foo ( $msg = '' ) { return $msg ; }

Funkce PHPDoc

  1. Podpora pro nejnovější verzi PHP
  2. Práce s třídami diagramů UML
  3. Fulltextové vyhledávání
  4. Podpora CI ihned po vybalení
  5. Více kontroly s DocBlocks

Verze PHPDoc

Aktuální verze PHPDocumentator 3, Repository

Funkce

  • Kompatibilní s PHP 7.0+ , plná podpora jmenných prostorů, smyček a dalších.
  • Docblock přes typy , docblock je explicitnější, pokud jde o typy, ne všechny formáty jsou podporovány php.
  • Vykreslí libovolnou značku , některé značky přidávají do phpDocumentoru další funkce (jako @link).
  • Nízké využití paměti , maximální využití paměti pro malé projekty je méně než 20 MB, pro střední projekty je to 40 MB a pro velké frameworky je to 100 MB.
  • Přírůstková analýza. Uložením souboru struktury z předchozího spuštění dojde k dalšímu zvýšení výkonu až o 80 % kromě výše zmíněného zvýšení rychlosti zpracování.
  • Jednoduché vytvoření šablony umožňuje vyvolat 1 úkol a upravit 3 soubory.
  • Proces ve dvou krocích  : phpDocumentor nejprve vytvoří mezipaměť se strukturou aplikace před generováním výstupu. Umožňuje používat vlastní nástroje nebo formátovače.
  • Obecná podpora , se statičtější analýzou v php, typy se staly složitějšími. phpDocumentor těmto typům rozumí. A zobrazí je jako prvotřídní typy [2] .

Aplikace

Při vývoji vlastních velkých projektů, jejichž všechny jemnosti nelze mít na paměti, stejně jako při finalizaci cizích projektů, musíte často nakouknout do dříve napsaného kódu. To vám umožní přesněji si představit vrácené, vytvořené objekty a co s nimi můžete dělat. Vzhledem k tomu, že PHP má implicitní přetypování typu , jsou při operacích prováděných na objektech různých typů potenciálně možné chyby. V silně typizovaných jazycích se to nestane - program se prostě nezkompiluje.

Aby se tomu zabránilo, používá se PHPDoc a další podobné technologie. Řekněme, že máme kód :

... $eventData = new EventData (); $eventData -> sender = $controller ; $eventData -> name = 'onDelete' ; $eventData -> group = 'global' ; $eventData -> argumenty = pole ( 'id' => 15 ); $eventDispatcher -> triggerEvent ( $eventData ); ...

Vývojář třetí strany, který čte tento kód, nemusí vědět, co $controller obsahuje, ale IDE mu řekne, zda podporuje PHPDoc. Tedy zadáním: $controller->- můžeme vidět, co je uvnitř. Díky tomu není potřeba pronikat do džungle kódu, abyste zjistili, co je tímto objektem předáváno a v jakém typu.

Odkazy

Poznámky

  1. ↑ fig-standards/phpdoc.md phpDocumentor/fig-standards // GitHub . Datum přístupu: 20. prosince 2015. Archivováno z originálu 31. března 2016.
  2. ↑ 1 2 Docker Hub . hub.docker.com _ Staženo: 24. září 2022.