Přesnější phpdoc pro pole

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

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

PhpStorm rozumí zápisu Token[]

PhpEd zatim nic nepodporuje.

• http://forum.nusphere.com/…s-t6633.html
• http://forum.nusphere.com/…s-t5837.html

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

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

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.

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)

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? ;)

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?

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

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 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.

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)

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í :(

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.

@sumiisakua: To je feature, ne bug.

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

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

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 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.

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.

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 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?

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.

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

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. :)

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ů.