Přesnější phpdoc pro pole

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
juzna.cz
Člen | 248
+
0
-

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
Nette Core | 1164
+
0
-

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
Nette guru | 2595
+
0
-

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
Člen | 392
+
0
-

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

PhpStorm rozumí zápisu Token[]

juzna.cz
Člen | 248
+
0
-

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?

David Grudl
Nette Core | 7790
+
0
-

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

Pavel Kouřil
Člen | 128
+
0
-

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

kukulich
Člen | 55
+
0
-

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

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

juzna.cz
Člen | 248
+
0
-

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

kukulich
Člen | 55
+
0
-

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

Andrewsville
Člen | 6
+
0
-

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.

juzna.cz
Člen | 248
+
0
-

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
Člen | 23
+
0
-

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

juzna.cz
Člen | 248
+
0
-

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
Člen | 746
+
0
-

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
Nette Core | 7790
+
0
-

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
Člen | 248
+
0
-

@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
Člen | 31
+
0
-

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š
Člen | 177
+
0
-

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
Člen | 1029
+
0
-

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
Člen | 2221
+
0
-

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
Člen | 55
+
0
-

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
Člen | 55
+
0
-

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
Člen | 6
+
0
-

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
Moderator | 4668
+
0
-

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

Andrewsville
Člen | 6
+
0
-

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š
Člen | 177
+
0
-

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
Člen | 36
+
0
-

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
Člen | 128
+
0
-

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
Člen | 1313
+
0
-

@sumiisakua: To je feature, ne bug.

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

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

kukulich
Člen | 55
+
0
-

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
Člen | 55
+
0
-

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
Člen | 55
+
0
-

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
Nette Core | 7790
+
0
-

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
Člen | 128
+
0
-

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
Člen | 55
+
0
-

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
Člen | 248
+
0
-

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
Nette guru | 2595
+
0
-

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
Člen | 1664
+
0
-

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
Člen | 55
+
0
-

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
Člen | 6
+
0
-

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
Člen | 1664
+
0
-

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
Člen | 248
+
0
-

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
Nette Core | 7790
+
0
-

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

Jan Jakeš
Člen | 177
+
0
-

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

Pavel Kouřil
Člen | 128
+
0
-

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
Nette guru | 2595
+
0
-

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
Člen | 407
+
0
-

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