PhD

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

PhD je nový systém pro generování PHP dokumentace. Přestože je stejně jako Livedocs (slibný, ale nikdy nenasazený systém) napsaný v PHP, ohromuje především svou rychlostí. Na rozdíl od současného systému (Docbook-XSL), kterému generování dokumentace trvá asi 3 hodiny, a Livedocs, který to zvládne za dvě (přičemž jeho hlavní výhoda je, že dokáže generovat stránky jednotlivě), to PhD zvládne za 3 minuty. Výsledkem by mělo být pravidelnější generování dokumentace a také jednodušší změny v HTML tvaru výsledku.

PhD se na rozdíl od Livedocs (a stejně jako Docbook-XSL) dá použít k převodu jakéhokoliv Docbook dokumentu a nejen PHP dokumentace a mohl by tedy mít širší podporu a lepší vývoj.

PhD má také jednu zvláštnost – pro své spuštění potřebuje patch PHP, který doplní podporu nového zápisu řetězců – tzv. nowdoc. Od heredoc se liší stejně jako se liší " od ', tedy tím, že se v něm neinterpretují proměnné. Osobně tomuto způsobu zápisu příliš nefandím a PHP raději používám oficiální, proto jsem si napsal jednoduchý převodník, který nowdoc převede na běžné apostrofy:

<?php
function nowdoc_remove($match) {
    return "'" . strtr($match[2], array("'" => "\\'", "\\" => "\\\\")) . "'";
}

function nowdoc_glob($dir) {
    foreach (glob("$dir/*.php") as $filename) {
        $file = file_get_contents($filename);
        $file = preg_replace_callback("/<<<~[ \t]*(.*)\n(.*)\n\\1\\s*/sU", 'nowdoc_remove', $file);
        file_put_contents($filename, $file);
    }
    foreach (glob("$dir/*", GLOB_ONLYDIR) as $dir) {
        nowdoc_glob($dir);
    }
}
?>

Pokud si budete chtít PhD vyzkoušet bez patchování PHP, tak funkci nowdoc_glob spusťte na adresář s PhD. Pokud chcete vidět výslednou vygenerovanou dokumentaci, můžete použít zrcadlo docs.php.net, ideálně byste neměli poznat žádný rozdíl.

Jakub Vrána, Ze zákulisí, 5.10.2007, diskuse: 11 (nové: 0)

Diskuse

Milan:

Mohu se zeptat, co způsobuje ten propastný rozdíl v délce generování? Děkuji

5.10.2007 10:42:18

LesTR:

Dobry den,
zajímalo by mě na jak velkém vzorku trvalo generovaní 3 resp. 2 hodiny? Dal by se systém porovnat s phpDocumentorem?

5.10.2007 12:54:00

Jakub Vrána :

Jednalo se o generování celé anglické dokumentace ve dvou verzích. S phpDocumentorem se to porovnat nedá, protože to je nástroj k jinému účelu.

5.10.2007 13:00:39

LesTR:

Díky za info. PhD neznám a ze zápisku nebylo jasné použití, proto to "srovnání" s phpDocumentorem.

5.10.2007 14:18:07

finc:

<rypnuti>Zajimalo by me, kolik lidi tuto moznost vyuzije. Uz jen proto, ze v PHP se velke projekty nedelaji a nedela se v nem ani zadne konstantni API.
Osobne jsem generoval dokumentaci snad jen jednou v zivote a to z duvodu "testu jak to bude vypadat".</rypnuti>

5.10.2007 23:49:10

Karel Dytrych:

<rypnuti>
To ze v php nedelate velke projekty vy jeste neznamena, ze se v nem nedelaji!
</rypnuti>

6.10.2007 00:25:49

finc:

Prave, ze jsem delal a vim, ze to neni dobra volba. Nechci vyvolavat nejaky flame.
Z osobni zkusenosti vim jak to je a obcas si k tomu neco prectu:
http://www.ukuug.org/events/linux2002/papers/html/php/

6.10.2007 21:03:02

Jakub Vrána :

Argumentace toho článku je bohužel poměrně chabá, navíc obsahuje několik chyb:

1. Když chci oddělit prezentační od aplikační logiky, je vhodné použít nějaký šablonovací systém. To je panečku objev! Navíc mě nenapadá, čím je tento objev specifický pro PHP.

2. Prý lze v PHP předefinovat existující funkce a prý dokonce i ty vestavěné. Když pominu speciální moduly jako Runkit, jak se to asi tak dá udělat? Autor si spíš spletl PHP a JavaScript.

3. Konfigurace celého serveru prý musí být nastavena centrálně. O možnosti měnit ji v httpd.conf nebo v .htaccess asi autor nikdy neslyšel.

4. Prý se nedá spolehnout na to, jaká verze PHP bude na serveru. U jiných jazyků je to snad jinak?

5. Perl spouštěný přes CGI si může nahrát vlastní moduly. PHP snad ne?

6. Autor bohužel nepochopil, že všechna pole v PHP jsou asociativní. Pouze když prvku nepřiřadím klíč, tak se přiřadí sám.

7. Na operátoru == je prý špatné to, že porovnává i různé typy. A na operátoru === zase to, že neplatí 3 === "3" :-).

8. To, že ve funkcích nejsou samy od sebe vidět globální proměnné, je prý nevhodná vlastnost pro vývoj velkých aplikací. Já to tedy vidím přesně naopak.

9. Autorovi vadí, že $_REQUEST obsahuje kromě $_GET a $_POST také $_COOKIE. Ale neuvádí žádný důvod, proč $_REQUEST vlastně používat místo oddělených polí.

Samozřejmě jsou v příspěvku i rozumné argumenty - absence jmenných prostorů (které jsou v reálu nahrazovány třídami, o čemž se autor ale nezmiňuje), zmatky s magic_quotes_gpc a register_globals nebo nekonzistentní pojmenování interních funkcí. Ale jako celek bych článek označil za poměrně chabou demagogii. Za článek vystihující považuji závěrečné doporučení: Místo PHP použijte na velké projekty raději Perl…

17.10.2007 13:24:53

Jakub Vrána :

Asi jsi také nepochopil, k čemu je nástroj určený. Těžko mohu dokumentaci jazyka PHP psát o jiném jazyku než o PHP :-).

(reakce na) 8.10.2007 14:00:03

Mordae:

Já dávám přednost návrhu projektu v `dia` a následnému vygenerování kompletní API dokumentace současně s kostrou PHP kódu. Dvě poslední věci jsou poměrně snadné, protože dia produkuje XML.

7.10.2007 15:04:29