PhpDoc u Api – návrh/prosba k @param
- Caine
- Člen | 216
Zdravím, začínám s Nette a zatím se mi tak nějak ze všech možnejch frameworků libí asi nejvíc, ale díky pár věcem jsou začátky s ním poměrně těžký a dosti zdlouhavý. Dokumentaci jako takovou tu asi nemá cenu ani zmiňovat, protože ta se píše dodatečně, ale u PhpDocu by tvůrci určitě mohli zapracovat už při psaní zdrojáků. Například u popisu některých, ne až tak jasných funkcí, by se určitě hodily detailnější popisky, nebo alespoň mini příklady použití, případně ukázku toho, co metoda vrací (když se vrací pole, tak jakou má strukturu, atp). A pak v Netbeans (určite nebudu jedinej, kdo je používá:) se mi u většiny metod neukazujou popisky parametrů. Je to tím, že u @param není uveden název parametru. Např.:
/**
* Inserts row in a table.
* @param mixed array($column => $value)|Traversable for single row insert or Selection|string for INSERT ... SELECT
* @return ActiveRow or FALSE in case of an error or number of affected rows for INSERT ... SELECT
*/
public function insert($data)se zobrází následovně:
Správně by měl být uveden i název parametru, tedy:
/**
* Inserts row in a table.
* @param mixed $data array($column => $value)|Traversable for single row insert or Selection|string for INSERT ... SELECT
* @return ActiveRow or FALSE in case of an error or number of affected rows for INSERT ... SELECT
*/
public function insert($data)který se zobrazí takto:
I na http://manual.phpdoc.org/…ter/default/ uvádějí @param se jménem parametru, takže by to tak asi být mělo:)
- Patrik Votoček
- Člen | 2221
NOTE: as of 0.4.1, @param can document phpdoc.de-style, with optional $paramname
Což je i logické, jelikož se to dá odvodit ze samotné definice funkce.
Pokud to NetBeans neumí tak je to spíš chyba na jejich straně, nikoli chyba na straně Nette Frameworku. :-)
- bojovyletoun
- Člen | 667
Nojo, a já si těch chybějících parametrů za ty měsíce nevšiml.
PS: BTW, taky vám NB ignoruje namespace Nette\Database\Table jeho třídy?
při new Nette\Database\ nabídne jen Diag\, Drivers\, Refl\,
Connection, Row, SqlLit, SqlPreprocessor, Statement. EDIT: restart
pomohl.
Editoval bojovyletoun (26. 12. 2011 23:23)
- Patrik Votoček
- Člen | 2221
Caine napsal(a):
Logický to možná je, ale zpětně kompatibilní evidetně ne, takže všichni, co používaj Netbeans (z mýho okolí snad všichni) a chtěj využívat nápovědu, maj prostě smůlu jen proto, že vývojáři Nette jsou líní..
Aha takže když jednou Nette u něčeho dodržuje standard tak je to špatně!? A když ho nedodržuje jinde tak je to taky špatně (PSR-0)!?
Vývojáři Nette nejsou líní ale dodržují standard, ve kterém je jasně řečeno že název parametru je volitelný.
Nox napsal(a):
PhpDoc („php standard“) to tam má. Jde o PHP = je to špatně v Nette
PhpDoc jako PHP standard to tam má jako volitelné = není to špatně v Nette (jelikož je to v souladu se standardem). :-)
To že stejný standard nedodržuje IDE (NetBeans) je problém onoho IDE a né Nette.
To by jsme taky mohli na konec každého souboru přidat komentáře s nastavením pro VIM. Do repa přidat složky s nastavením projektu pro všechna IDE a neIDE.
- hrach
- Člen | 1838
Jestli tu ještě někdo řekně něco o lenosti, budu Davida osobně žádat o trvalý ban. Jestli okamžitě nezaložíš issue na Netbeans, opět budu Davida osobně žádat o trvalý ban.
Myslím si, že by se to přidat mělo, kvůli unifikaci phpdoc v rámci frameworku. Není to tám z důvodu portace z notorm, které toto nepoužívá, a David to tak tenkrát nechal.
Jestli ti to stále vadí, napiš pull. Už to někdo zavřete ;)
Editoval hrach (27. 12. 2011 10:31)
- Ondřej Brejla
- Člen | 746
Samozřejmě to je buga…já jí rovnou zadám. Kdyby jí Caine místo nesmyslného dloubání do Nette rovnou zadal, ušetřil mi čas na její fixnutí.
- David Grudl
- Nette Core | 8228
Caine napsal(a):
…jen proto, že vývojáři Nette jsou líní..
Kdyby „vývojáři Nette“ nebyli líní, tak Nette neexistuje, protože by spokojeně používali Zend.