Přesnější phpdoc pro pole

juzna.cz

@llook: +1.

V praci nam na projektech apigen strasne padal (jeste stara verze bez TokenReflection). Ale kvuli duplikovanym tridam bylo potreba upravovat RobotLoader, tzn sahat do Nette, protoze to on nekompromisne hazel vyjimky a odmital pracovat. (predpokladam, ze se to od te doby nezmenilo)

Editoval juzna.cz (29. 2. 2012 0:48)

kukulich

Zend by skoro neřešil. Ti jsou prostě zaseklí u DocBloxu. Mají pocit, že to inkrementální generování dokumentace funguje (což si myslím, že ne) a díky tomu, že to je rychlé.

Pokud chcete apelovat, tak spíš jinde. Třeba zjistit, proč Doctrine 2.2 má takovouhle dokumentaci http://www.doctrine-project.org/…/orm/2.2/api, stará 2.1 vypadala takhle http://www.doctrine-project.org/…/orm/2.1/api

Já asi nemám jako jeden z autorů ApiGenu chuť se někde tlačit, přišlo by mi to blbé…

kukulich

juzna.cz napsal(a):

@llook: +1.

V praci nam na projektech apigen strasne padal (jeste stara verze bez TokenReflection). Ale kvuli duplikovanym tridam bylo potreba upravovat RobotLoader, tzn sahat do Nette, protoze to on nekompromisne hazel vyjimky a odmital pracovat. (predpokladam, ze se to od te doby nezmenilo)

Duplicitní třídy nemáme rádi pořád, ale změnit to z výjimky na warning bychom asi mohli. Přesněji už nás dneska napadlo i pár dalších možných variant, jak se s některými situacemi vypořádat.

David Grudl

kukulich napsal(a):

Já asi nemám jako jeden z autorů ApiGenu chuť se někde tlačit, přišlo by mi to blbé…

Jardo to je naprostá ptákovina, pokud nezatlačíš ty, nezatlačí nikdo. Úplně stejně mluvil před lety Martin Malý, podívej se na jeho postoje dnes.

Máš obrovskou výhodu, že to budeš propagovat venku a nikdo ti neřekne ani ň, že propaguješ svůj produkt. U nás bys byl za čur**a.

Pavel Kouřil

Jan Tvrdík napsal(a):

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

Jak asi. Prostě vezmou výjimky z někama, copypastnou je jinam a neupraví namespace. :)

Ještě větší sranda bylo to, když v jedné třídě házeli „throw new Exception“, nicméně Exception v aktuálním NS byl interface. Nicméně to jsem neopravoval. :)

Co na duplicitní třídy mít něco jako přepínač –liberal? Nicméně rozhodně bych nechal možnost mít nějaký „mód“, který by se vůči programátorovi choval fakt docela drsně a nekompromisně; přecijen, duplicitní názvy tříd JSOU bezpochyby prasárna a já budu rád, když mě za ně něco seřve. A ani ti kluci ze Zendu je tam mít nechtějí, jen to nikdo nepoužívá, tak to asi nikdo neodhalil, no.

Jinak klidně bych zkusil s propagací pomoct, kdyby byl zájem. :)

Vojtěch Dobeš

kukulich napsal(a):

Já asi nemám jako jeden z autorů ApiGenu chuť se někde tlačit, přišlo by mi to blbé…

Stejně jako je kvalitní produkt ApiGen výborná služba uživatelům projektů, které ho na svou dokumentaci nasadily, tak úplně stejně dobrou službou je jeho šíření mezi další projekty. Kdo z toho má přínos jsou na konci zase programátoři, kteří se nesetkají s hnusem, ze kterého bolí hlava, ale s typograficky hezkou stránkou, kde je radost si proklikávat zdrojáky…

Editoval vojtech.dobes (29. 2. 2012 12:26)

Jan Jakeš

Jen pro info, u Zendu jsem to zkusil, ale jestli jsou všichni tak tvrdohlaví jako při diskusi o XSS na Jakubově blogu, tak tomu nedávám nejmenší šanci. Jsem ale zvědavej na nějakou vtipnou odpověď :)

David Grudl

Voni jsou tvrdohlaví a pak za pár dní napíšou, že „While automatic contextual escaping would be amazing to have, the knowledge and tools needed to build such a solution while maintaining reasonable performance is a non-trivial task beyond our current capabilities.“

Moc se těším, až to použiju na microsite o Latte :-)

Jan Jakeš

Haha, pěkně :)

Diskuse se přesunula do mailing listu a začíná to být zajímavé: http://zend-framework-community.634137.n4.nabble.com/…4435064.html :)

David Grudl

Apigenisti, převezměte tu feature, že v levém panelu je aktivní celý řádek, viz http://apigen.juzna.cz/…nd_Date.html vs https://api.nette.org/nette/2.1/. Pro mě osobně je to killer feature :-))

(a přegenerujte pak zend)

kukulich

Sledujeme pečlivě všechny forky (i nette-buildtools) :) Tvoje implementace se nám, Davide, ne úplně líbila, ale Ondrova vypadá podle náhledu (https://github.com/…gen/pull/111) lépe. Kouknu večer.

Jinak se mi líbil ten autofocus do vyhledávání, co si teď přidal na overview, ale Andrewsville byl proti :)

juzna.cz

Andrewsville napsal(a):

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.

Sluzba je, zdrojaky ma na GitHubu, i kdyz stale je tam co dodelavat. Co dal?

Realizuj se, komunito, budu rad za forky/pully/issues.

Jan Jakeš

Co tomu dát rychle nějaký základní vzhled pomocí Bootstrapu?

Pak bych navrhoval buď přesunout na doménu ApiGenu anebo rovnou vymyslet nějaký název a použít novou doménu.

A dále už jen trochu propagovat, a díky tomu propagovat i ApiGen :)

juzna.cz

@Juan: presne to sem mel v planu, tak jsem se kvuli tomu dnes naucil CSS a bootstrap a uz je to tam ;) Jakekoliv pripominky vitany, nebo klidne i pull requesty.

@kukulich @Andrewsville: chcete to dat nekam k vam?

Vojtěch Dobeš

@juzna.cz Tleskám! Dobrá práce.

petr.pavel

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

Rád bych se vrátil k tomu, jakému zápisu rozumí IDE. Zkoušel jsem replikovat tvůj screenshot v NetBeans 7.1.1 (čerstvá instalace, edice pro PHP) a nepodařilo se mi to. Dostanu „No suggestions“ místo getList(). Co musím udělat proto, aby mi to fungovalo?

Předtím jsem zkoušel jiný kód a chtěl jsem dostat nápovědu pro vlastnosti objektu – pochopitelně to taky nefungovalo. Token[], array(Token) i array<Token>

Eclipse (http://ukaz.at/274), NetBeans (http://ukaz.at/275).

juzna.cz

petr.pavel napsal(a):

Zkoušel jsem replikovat tvůj screenshot v NetBeans 7.1.1 (čerstvá instalace, edice pro PHP)

Ja jsem zkousel nejnovejsi NetBeans, co jsem v rychlosti nasel a stahnul (ale jinak ho nepouzivam). Asi to byla nejaka 7.2ka. Do budoucna to tedy NetBeans podporovat bude (v dalsi verzi asi?).

Navic kdyz je uvedeno jako navratovy typ array, tak ti taky nic nenapovi (a ani zadne jine IDE). Pouzivani presnejsi anotace tedy nikdy nepovede k horsimu stavu, pouze k lepsimu.

Ondřej Brejla

petr.pavel: NetBeans 7.2dev…http://ukaz.at/281 (resp. http://ukaz.at/282)

Editoval Ondřej Brejla (20. 3. 2012 16:41)

juzna.cz

Tak konecne se nekdo (@hrach) odhodlal: https://github.com/…tte/pull/604

Je tedy jeste nekdo/neco proti?

juzna.cz

Na GitHubu vyvstala diskuse, jak zapisovat vicerozmenra pole.

Puvodni zapis v Nette byl @var array of [name => array of IMacro].

Navrh byl zapisovat to stylem jako v C++, tedy IMacro[][] bez jakychkoliv informaci o typu indexu. Ty by byly popsany az pro uzivatele ve zbytku docbloku. Nove tedy @var IMacro[][] array of [name => array of IMacro].

Ted zjistit jak je na tom podpora IDE, zkuste:
PhpStorm tento zapis nepodporuje; udela z toho jednorozmerne pole, takze jakmile pouzijeme 2 indexy, je ztracen.
NetBeans 7.2 to jaktakz podporuje, resp. vsechno bere jako pole i nepole zaroven.

Editoval juzna.cz (26. 3. 2012 10:44)

Jan Tvrdík

+1 pro zápis převzatý z C++

juzna.cz

Jak je na tom s podporou PhpEd?

llook

Bez jakýchkoli informací o typu indexu je i ta konvence pro jednorozměrné pole. Zápis IMacro[][] nevnímám jako nějakou novou konvenci, ale pouze jako aplikaci stávající konvence.

Pokud typ pole obsahující položky typu string zapisuju jako string[], tak logicky typ pole obsahující položky typu string[] budu zapisovat jako string[][].

Patrik Votoček

Btw když už jsme u toho jak zapsat anotaci Iterátoru / ArrayAccessu? Řekněme že mám pole FooEntity které je uložené v ArrayHash (iterátor s array accessem).

llook

Patrik Votoček napsal(a):

Btw když už jsme u toho jak zapsat anotaci Iterátoru / ArrayAccessu? Řekněme že mám pole FooEntity které je uložené v ArrayHash (iterátor s array accessem).

Asi z čistě praktických důvodů bych použil zápis ArrayAccess|FooEntity[].

David Grudl

Stejně je ten zápis string[] zavádějící, protože jde o postfixovou konvenci, tedy prvořadá informace, že jde o pole, se uvádí až na druhém místě. Rozdíl mezi řetězcem string a polem string[] není na první pohled tak zřejmý.

juzna.cz

Patrik Votoček napsal(a):

Btw když už jsme u toho jak zapsat anotaci Iterátoru / ArrayAccessu? Řekněme že mám pole FooEntity které je uložené v ArrayHash (iterátor s array accessem).

V PhpStormu na to funguje hack: @return \ArrayIterator|Foo[].
Prvni cast mluvi pravdu ale je IDEcku na nic, druha cast lze a presvedci IDEcko napovidat.

juzna.cz

David Grudl napsal(a):

Stejně je ten zápis string[] zavádějící…

ale je to kratke a jednoduche, tzn easy pro pouziti pro bezne lidi

Editoval juzna.cz (26. 3. 2012 21:48)

hrach

Hosi, uz se tu zase resi pitomosti. ten commit jsem udelal hlavne proto, dek funguji IDE. PhpEd ve verzi 7 (kretou uz mam zase odinstalovanou) podporuej urcite Foo[]. Slozitejsi typy predpokladam klasicky failnou. Proto dany commit resi to, co funguje.

Vojtěch Dobeš

Ad čitelnost: to je docela dobrá poznámka, totiž zrovna u dokumentace (která je čistě pro čtení) preferovat syntaxi výhodnější při zápisu mi přijde paradoxní. Ale jestli pak všechna IDE napovídají, tak… :)

maryo

Taky tenhle zápis používám. U asociativních polí ještě navíc uvádím string jako typ klíče. Jak byste zapsali typehint pro asociativní pole, jehož prvky můžou být buď instancí A nebo instancí B? Umí/bude umět ApiGen něco takovýho? Já to zapsal nakonec takhle:

@param (IDecoder|IEncoder)[string] $codecs

A koukám, že v phpDocumentoru na to mají otevřenej bug a ten někdo to zapsal stejně. Možná, že to tam někdy bude fungovat.

https://github.com/…2/issues/419

Editoval maryo (22. 4. 2012 23:17)