Přesnější phpdoc pro pole

juzna.cz

Hodně metod frameworku pracuje s polemi objektů, z čehož ale PHP rozumí pouze slovu pole. To je škoda, protože takové IDE pak nemůže jednoduše napovídat. A i člověk musí bádat a procházet zdroják, aby vykoumal, co vlastně v onom poli je.

Např tato metoda, co asi vrací?

	/**
	 * Process all {macros} and <tags/>.
	 * @param  string
	 * @return array
	 */
	public function parse($input) { ... }

To, že je výsledkem pole mi moc nepomůže. Raději bych věděl, že jde o pole tokenů, neboli Token[].

Nebyl by takovýto PhpDoc srozumitelnější?

	/**
	 * Process all {macros} and <tags/>.
	 * @param  string
	 * @return Token[]
	 */
	public function parse($input) { ... }

Mně by to o dost usnadnilo život. Jednak tomu rozumí moje IDE, a tudíž bude vědět, jak s položkami pracovat:

$tokens = $parser->parse($code);
$tokens[0]->; // zde napovi
foreach($tokens as $token) $token->; // zde take

a druhak tomu rozumím já a když se na kód mrknu, hned je mi jasné čeho že je to pole.

Stejně to platí pro properties a argumenty funkcí.

Rozumí tomuto zápisu i ostatní IDE? (asi to nebudou umět všechny, ale snad většina)
Nestálo by za to začít psát anotace pořádněji?

Díky za vaše názory

Felix

Sice jsem nezkousel jestli to phpStorm|netbeans umej taky, ale neni to tak spatnej napad, jde o to jestli to neni v rozporu s nejakou konvenci ci co.. ale jinak se mi to libi

Jan Tvrdík

Zásadní problém je, že neexistuje standard, podle kterého by se to mělo psát. Návrhů existuje mnoho. Upravit zdrojové kódy Nette není problém. Naučit s tím pracovat ApiGen také problém nebude. To, na čem to stojí a padá je podpora v editorech. Nejprve je tedy potřeba zjistit, které IDE to podporují a jaký konkrétní formát podporují. Poté by bylo pěkné, kdyby vítězný formát prohlásil ApiGen za standard a Nette ho pak může s chutí používat.

paranoiq

taky se někdy používá array(Token) nebo array<Token>

PhpStorm rozumí zápisu Token[]

juzna.cz

Kdyz se podivame do jinych jazyku, tak v Jave se pole zapisuji Token[], C# taktez.

NetBeans tomuto zapisu take rozumi (dukaz http://ukaz.at/22r).

Co dalsi IDE, hlavne PhpEd?

hrach

PhpEd zatim nic nepodporuje.

David Grudl

Tohle je velká příležitost pro kluky z Apigenu, aby ten standard vytvořili.

Pavel Kouřil

Já osobně jsem pro Class[] – přijde mi to takové nejpopisnější (a nejjednodušší na napsání) :)

kukulich

ApiGen formát Class[] podporuje už od verze 2.3.0 :)

http://api.nella-project.org/…inition.html#…

juzna.cz

@kukulich: ale chtelo by to mit zdokumentovane, at se na to da odkazovat.

kukulich

Andrewsville slibuje dokumentaci anotací už asi dva týdny :)

Andrewsville

kukulich napsal(a):

Andrewsville slibuje dokumentaci anotací už asi dva týdny :)

Tento lživý příspěvek mě donutil se tu registrovat! :-P

Každopádně dokumentace je v plánu, jenom se k tomu dokopat. Kdysi jsme se dokonce chtěli spojit s autorem DocBloxu, abychom takový standard vytvořili. Tak tu myšlenku možná oživíme.

llook

Netbeans 7.1 to neumí, ale Apigen to umí: http://screencast.com/t/uBVzdY1p0

juzna.cz

Pristi vikend je posobota (asi) v Brne, tak bychom mohli udelat nejaky hackaton a spolecne tu dokumentaci k ApiGenu vytvorit ;)

Editoval juzna.cz (16. 2. 2012 17:58)

hason

@Andrewsville Generátor dokumentace DocBlox také podporuje zápis Type[] http://docs.docblox-project.org/…s/types.html#…

juzna.cz

Apigen zapisu rozumi, DocBlox take, a autor phpdoc.org mi psal, ze web rusi a delaji presmerovani na docblox. Takze byzme to pomalu mohli zacit rozjizdet, ne? ;)

Ondřej Brejla

NetBeans v 7.2 dev verzi zvládá code complete u typu Class[]… Zpětné vygenerování správného PHPDoc Class[] typu je v plánu, stejně jako další improvementy. Každopádně je počítáno se zápisem Type[]. Případně u vícetypových polí nejspíš Type[]|Class[].

David Grudl

juzna.cz napsal(a):

Apigen zapisu rozumi, DocBlox take, a autor phpdoc.org mi psal, ze web rusi a delaji presmerovani na docblox. Takze byzme to pomalu mohli zacit rozjizdet, ne? ;)

Koukám, jaký paskvil leze z DocBloxu. Ufff. To jako fakt někdo může používat třeba tohle? Proč to raději nepřesměruje na Apigen?

juzna.cz

@DavidGrudl: taky jsem se hodne divil, ale jsou v tom lidi kolem Zendu a samotnej Zend si v tom dela dokumentaci. A tem to nerozmluvime. Zend ma proste svuj svet. Ale zkusim vic zatlacit, minimalne z principu.

Zde je prepis mailove komunikace.

Editoval juzna.cz (27. 2. 2012 23:00)

grongor

David Grudl napsal(a):
Koukám, jaký paskvil leze z DocBloxu. Ufff. To jako fakt někdo může používat třeba tohle? Proč to raději nepřesměruje na Apigen?

wow … doted jsem si Apigenu dostatecne nevazil :D

Jan Jakeš

Kluci z ApiGenu, nechcete se toho chopit a trochu na ně zatlačit? Kdyby někdo objektivně sepsal výhody ApiGenu (Token reflection, PHP 5.4, …) a pokusil se vysvětlit proč je Docblox… ehm, paskvil, třeba by ještě změnili názor, ne?

Navíc (jak už někde bylo řečeno) PHPDoc by fakt potřeboval standard – a to by mohl být hlavní argument (že se ho ApiGen chystá definovat).

Možná úplně nejlepší by byla forma článku, abysme mohli i my ostatní v komentářích podpořit :)

Tharos

David Grudl napsal(a):

juzna.cz napsal(a):

Apigen zapisu rozumi, DocBlox take, a autor phpdoc.org mi psal, ze web rusi a delaji presmerovani na docblox. Takze byzme to pomalu mohli zacit rozjizdet, ne? ;)

Koukám, jaký paskvil leze z DocBloxu. Ufff. To jako fakt někdo může používat třeba tohle? Proč to raději nepřesměruje na Apigen?

Tohle je předem prohraný boj. A to z jednoho prostého důvodu: DocBlox má incredible support for PHP 3.5. Tomu se prostě nedá konkurovat.

Patrik Votoček

Nehledě na to že DocBlox už tu dokumentaci má kdežto ApiGen ne (dokud jí mít nebude jaksi to nemá smysl řešit).

kukulich

Patrik Votoček napsal(a):

Nehledě na to že DocBlox už tu dokumentaci má kdežto ApiGen ne (dokud jí mít nebude jaksi to nemá smysl řešit).

ApiGen má dokumentaci svého fungování, stejně tak DocBlox. Dokumentace anotací nebyla předtím potřeba, protože jako standard se bral PhpDoc. Potřeba definovat nový standard začala vznikat až v poslední době. DocBlox sice nějakou dokumentaci má, ale většinou vypadá asi takto: http://docs.docblox-project.org/…recated.html

Nový standard jsme začali rozepisovat a chtěli jsme ho definovat společně třeba s DocBloxem. Otázkou je, jestli to má teď smysl, protože pokud phpdoc.org bude směřovat na DocBlox, tak se standardem stane on.

kukulich

Jinak DocBlox není paskvil, jen funguje jinak než ApiGen. Třeba ohledně duplicitních tříd mají prostě oba projekty na danou věc jiný názor. Ano, má podle mě hnusnou šablonu a vůbec se mi na něm pár věcí nelíbí, ale to je věc názoru.

DocBlox vítězí nad ApiGen nyní hlavně proto, že si ho vybral Zend. To je prostě reklama jako prase. A bohužel zatím není nic jiného velkého a známého, co by si zvolilo ApiGen. Framework FuelPHP sice od DocBloxu utekl k ApiGenu (https://twitter.com/#…), ale nakonec API dokumentaci zrušil úplně. A třeba Benjamin Eberlei sice má rád ApiGen (https://twitter.com/#…), ale dokumentace Doctrine jím generována není.

Možná ApiGenu pomůže Netbeans 7.2, jinak prostě čeká velkou rybu, která ho začne používat.

Andrewsville

Mimochodem, Doctrine má issue na generování API pomocí ApiGenu (díky HosipLan za založení), ale už je taky pěkně fousaté http://www.doctrine-project.org/…owse/DWEB-85 :(

Podle mě má ApiGen nevýhodu v tom, že je hodně striktní a celkem kašle na nějaké legacy věci. Nedporuje @property, @method tagy, ani relikty dávných dob jako @final, @abstract a podobně, nedovolí víc tříd, funkcí ani konstant se stejným názvem (FQN), nepodporuje podmíněně definované elementy (definice třídy v IFu). Všechny tyhle vlastnosti jsou úmyslné a nechceme je měnit, protože jsou „fuj“, ale Bežnému Frantovi Programátorovi můžou vadit.

Oproti DocBloxu mu chybí snad jen ta podpora inkrementální dokumentace, ale ta se podle našeho názoru nedá spolehlivě vyřešit (nebo to bude šílená jaderná elektrárna), takže jsme se na to vykašlali.

Jinak i DocBlox používá statickou reflexi (ekvivalent naší TokenReflection), ale taky předpokládám, že méně striktní (za většinu chyb a hotfix releasů ApiGenu můžou chyby v parsování zdrojáku v TR, protože celá TR funguje stylem fail early, fail often).

Mám(e) :) v plánu něco, co by mohlo ApiGen ještě víc rozšířit, ale je to, jako všechno, běh na delší trať. Na Twitteru se objevil nápad, že by mohla existovat služba, která dokumentaci zdrojáku třeba z Githubu vygeneruje a případně ji bude i hostovat.

Editoval Andrewsville (28. 2. 2012 14:36)

Filip Procházka

@**Andrewsville**: To je super nápad! Píšu si „todo: prostudovat github api“ :)

Andrewsville

HosipLan napsal(a):

@**Andrewsville**: To je super nápad! Píšu si „todo: prostudovat github api“ :)

Já už na to mám virtuál, jenom ten čas mi chybí :(

Jan Jakeš

Je to škoda. Myslíte, že by vývojářům Zendu nedošlo, že je ApiGen poněkud použitelnější, kdyby jim třeba někdo poslal API Zendu vygenerované v ApiGenu? To, co má Zend teď (http://framework.zend.com/apidoc/core/), je podle mě naprosto zoufalé. Nevím jak moc se liší ApiGen a Docblox unvitř, ale jako uživatel/programátor tam vidím opravdu propastný rozdíl.

sumiisakua

Raději bych viděl ApiGen jako „hlavní“ směr.
Zkoumal jsem DocBlox a došel jsem k závěru, že pokud chcete dát zabrat prohlížeči a kousnout ho, tak si otevřte api vytvořenou pomocí DocBlox.

Pavel Kouřil

Jen tak cvičně jsem zkusil pro zf2 vygenerovat api a vyfailuje to při ~51% na Class "Zend\Markup\Renderer\Markup\Html\Replace" is already defined in file "C:\work\php\zf2-orig\library\Zend\Markup\Renderer\Markup\Html\Replace.php" :)

Takže to asi nepude, no … nebo dělám něco špatně :)

redhead

@sumiisakua: To je feature, ne bug.

Ale vážně, to kousnutí jsem nepochopil :)

Editoval redhead (28. 2. 2012 19:27)

kukulich

Pajka napsal(a):

Jen tak cvičně jsem zkusil pro zf2 vygenerovat api a vyfailuje to při ~51% na Class "Zend\Markup\Renderer\Markup\Html\Replace" is already defined in file "C:\work\php\zf2-orig\library\Zend\Markup\Renderer\Markup\Html\Replace.php" :)

Takže to asi nepude, no … nebo dělám něco špatně :)

Zend2 obsahuje chyby, v tomto konkrétním případě je stejné jméno třídy definované 2×. ApiGen záměrně padá, protože duplicitní třídy považujeme za zlo. A v případě dokumentace je navíc pak dost těžké generovat strom předků a potomků.

Zend1 se ApiGenem vygeneruje bez problémů.

kukulich

Juan napsal(a):

Je to škoda. Myslíte, že by vývojářům Zendu nedošlo, že je ApiGen poněkud použitelnější, kdyby jim třeba někdo poslal API Zendu vygenerované v ApiGenu? To, co má Zend teď (http://framework.zend.com/apidoc/core/), je podle mě naprosto zoufalé. Nevím jak moc se liší ApiGen a Docblox unvitř, ale jako uživatel/programátor tam vidím opravdu propastný rozdíl.

My to dělat nebudeme. Přišlo by nám asi trochu hloupé se tam takhle cpát. Pokud to někdo chcete udělat, tak se tomu samozřejmě nebráníme a hlavně si rádi přečteme zdůvodnění proč DocBlox :)

kukulich

A ještě mě napadlo, že problémem ApiGenu může být to, že je postaven nad Nette. Chtěli byste mít jako autoři frameworku dokumentaci generovanou jiným frameworkem? :)

David Grudl

kukulich napsal(a):

A ještě mě napadlo, že problémem ApiGenu může být to, že je postaven nad Nette. Chtěli byste mít jako autoři frameworku dokumentaci generovanou jiným frameworkem? :)

Ale klidně, jenže žádný lepší holt neexistuje ;-)

Ale vážně, API dokumentace je pro uživatele, nikoliv pro tvůrce. Pokud se ukáže třeba uživatelům Zendu nebo zmíněného SugarCRM, jak by to mohlo vypadat, tak to budou chtít, framework neframework. Přece nikdo nevěří, že někdo používá onen browser killer. Touhle cestou bych šel, pěkně po Leninsku udělat revoluci zdola.

Pavel Kouřil

Nedalo by se třeba zobrazit i, ve kterém souboru to je definováno podruhé? :) Ono by to pár věcí pak usnadnilo … a –debug to neukáže, bohužel :/

kukulich

Pajka napsal(a):

Nedalo by se třeba zobrazit i, ve kterém souboru to je definováno podruhé? :) Ono by to pár věcí pak usnadnilo … a –debug to neukáže, bohužel :/

Vždycky jsem to Andrewovi chtěl navrhnout a vždycky na to zapomenu :) Ale teď už na to snad nezapomeneme.

juzna.cz

Udelal jsem na rychlo takovyho strasne jednoduchyho build-bota pro ApiGen: http://apigen.juzna.cz/
(early dev phase, kdo chce prispet je vitan; zatim jsem na tom stravil 2hod i s rekompilaci PHPka na hostingu, takze prosim na to berte zretel…)

Jan Tvrdík

Super. U Symfony z nějakého důvodu kus vygenerované dokumentace chybí http://apigen.juzna.cz/…e.Shell.html a celkově to generování probíhá až nepřirozeně pomalu.

Honza Marek

Pěkný. Akorát apigen trochu blbne, pokud se mu daj dvě namespace (viz WebLoader), který jsou stejný, ale lišej se velikostí některých písmenek. Pak by byla na apigen.juzna.cz fajn funkce pro aktualizaci dokumentace.

kukulich

Honza Marek napsal(a):

Pěkný. Akorát apigen trochu blbne, pokud se mu daj dvě namespace (viz WebLoader), který jsou stejný, ale lišej se velikostí některých písmenek. Pak by byla na apigen.juzna.cz fajn funkce pro aktualizaci dokumentace.

Otázka: Myslíš, že to máme brát jako bug ApiGenu a zkusit to nějak fixnout? Nebo to spíš nechat na autorovi knihovny?

Andrewsville

juzna.cz napsal(a):

Udelal jsem na rychlo takovyho strasne jednoduchyho build-bota pro ApiGen: http://apigen.juzna.cz/
(early dev phase, kdo chce prispet je vitan; zatim jsem na tom stravil 2hod i s rekompilaci PHPka na hostingu, takze prosim na to berte zretel…)

Toto je kvalitní příspěvek! Super práce!

Honza Marek napsal(a):

Pěkný. Akorát apigen trochu blbne, pokud se mu daj dvě namespace (viz WebLoader), který jsou stejný, ale lišej se velikostí některých písmenek. Pak by byla na apigen.juzna.cz fajn funkce pro aktualizaci dokumentace.

No, ano. TokenReflection je totiž – narozdíl od PHP – case sensitive. Jestli je to dobře nebo ne, je otázka. Zatím si myslíme, že ano, protože (stejně jako ApiGen) svým chováním trochu i „vychovává“.

Honza Marek

Jak tam mám namespace

Webloader
WebLoader
- Filter (pro Webloader\Filter)
- Filter (pro WebLoader\Filter)

to určitě dobře neni. S vychováváním souhlasim, ale mělo by být pokud možno realizováno vypisováním warningů. Ty ale v apigen.juzna.cz logicky neuvidím.

juzna.cz

Honza Marek napsal(a):

… Ty ale v apigen.juzna.cz logicky neuvidím.

Zatim neni, ale bude. https://github.com/…tor/issues/2

David Grudl

kukulich: nechceš hodit do internals link na vygenerovanou dokumentaci u juzny?

Jan Jakeš

Jestli chcete, tak můžu zkusit Zend s nějakou issue nebo mailem (co je lepší?).

Pavel Kouřil

Já se o apigenu zmínil na IRC, když jsem řešil tento pull … a nějak moc nikdo nejevil zájem si o tom zjistit něco víc :)

Nicméně můžeš zkusit udělat třeba issue nebo poslat mail do nějakého mailing listu (pokud mají?) nebo napsat na nějaké offic fórum (pokud je?). :)

Ale pokud jim vyhovuje Docblox, který shodí celý prohlížeč při použítí vyhledávání v menu … tak s tím nic nenaděláme. Maximálně tak zkusit co nejvíc apelovat na tu uživatelskou základnu. :(

PS: Přišel někdo z vás na to, jak v Docbloxu poslat odkaz přímo na nějakou třídu? (FŮJ IFRAMY)

PPS: Je krásně vidět, jak některé části Zendu jsou naprosto nepoužitelné a nikdo je asi v životě nenasadil do žádné app … jinak si tolik duplikátních názvů tříd (viz ten pull) nedokážu fakt představit. :)

Jan Tvrdík

Pajka wrote:

PPS: Je krásně vidět, jak některé části Zendu jsou naprosto nepoužitelné a nikdo je asi v životě nenasadil do žádné app … jinak si tolik duplikátních názvů tříd (viz ten pull) nedokážu fakt představit. :)

Tak to je fakt síla. Jak se jim tam takový bordel mohl dostat fakt nechápu.

llook

kukulich napsal(a):

Zend2 obsahuje chyby, v tomto konkrétním případě je stejné jméno třídy definované 2×. ApiGen záměrně padá, protože duplicitní třídy považujeme za zlo. A v případě dokumentace je navíc pak dost těžké generovat strom předků a potomků.

Dokud šlo pouze o nástroj na dokumentaci Nette a Dibi, tak OK, ale pokud máte ambici to víc rozšířit, tak vám tohle ubírá body.

Vžijte se do uživatele ZF, který se rozhodne, že si vygeneruje vlastní API dokumentaci, aby nemusel používat ten paskvil. Samozřejmě ihned zavrhne nástroj, který mu v polovině řekne (jinými slovy): „Blbě programuješ, oprav si to, nebo žádnou dokumentaci nedostaneš.“ Jeho první zkušenost s Apigenem bude negativní a proto i na dlouho poslední.

Kdyby to třeba radši vyštěklo nějaké varování, přeskočilo daný soubor a pokračovalo dál, bylo by to o dost lepší. Kdyby to ta varování navíc posbíralo a přidalo do vygenerované dokumentace (tak to myslím dělával phpDocumentor), bylo by to úplně super.

Pak si hypotetický uživatel vygeneruje dokumentaci k ZF, včetně dokumentace toho, že je v něm nějaká pro něj nepříliš významná chyba a pokud se mu to bude líbit, tak je šance, že tím nakazí dalších pár jedinců.