PhpDoc u Api – návrh/prosba k @param

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

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

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

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)

Caine
Člen | 216
+
0
-

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í.. S takovým přístupem si Nette na popularitě rozhodně nezíská.

hrach
Člen | 1834
+
0
-

Caine: java doc („průmyslový standard“) tam to nemá. proč duplikovat informaci? To bych nenazýval leností. Pokud na nekoho ukazovat, pak na vyvojare netbeans.

Nox
Člen | 378
+
0
-

PhpDoc („php standard“) to tam má. Jde o PHP = je to špatně v Nette

Editoval Nox (27. 12. 2011 9:49)

Patrik Votoček
Člen | 2221
+
0
-

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 | 1834
+
0
-

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)

Nox
Člen | 378
+
0
-

Smím se zeptat kde? Díky předem

V manuálu phpdoc.org je jediná zmínka o volitelnosti jedna spíš podivně napsaná poznámka pod čarou… jinak i tam jsou v úplně všech zápisech a příkladech uváděny u @param všechny názvy proměnných.

Editoval Nox (27. 12. 2011 10:40)

Ondřej Brejla
Člen | 746
+
0
-

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

Issue: http://netbeans.org/…show_bug.cgi?…

David Grudl
Nette Core | 8074
+
0
-

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.