Jsem na nervy z dokumentace

Dokumentace Příručka je jednoduché představení základní funkčnosti. Částečně to musí být také PR. Představ si to jako výstřih slečny se kterou jdeš poprvé na rande. Abys pokračoval dál, mělo by Ti dát příslib. :)

Editoval Pavel Kravčík (19. 6. 2017 11:30)

Co si pamatuji Symfony bylo to tam obdobně. Vše bylo simple, beautiful and must have any serious app. Po projetí quickstartu a tutorialu bys měl být schopný jako zkušenější programátor v pohodě použít API, pokud Tě to zajímá do detailu.

Nette je skvělé. A co přesně potřebuješ, co tam není?

@Kaven muzes dat tri priklady? Mam ted kolem sebe dva zacatecniky, tak bych to s nima prosel. Diky

Chemix: Tak zrovna teďka – potřebuju získat raw data z POST. Z dřívějška už mám představu že budu potřebovat nějaký objekt httpRequest. Pogoogloval jsem a našel tohle: https://doc.nette.org/cs/http/request . Je někde napsáno že se z toho dají dostat raw data? Myslím že ne, a přitom v kódu vidím nějakou funkci getRawBody(). Funguje? Nefunguje? Není náhodou jen interní? Nemám páru, musím to vyzkoušet. A nebýt toho že jsem se díval do zdrojáku, tak o ní ani nevím.

Dále na té stránce je napsáno, že request se má získat z DI kontejneru takto: $httpRequest = $container->getByType(‚Nette\Http\Request‘); . Princip DI jsem si nastudoval z odkazované stránky, dokonce jsem ho už používal (už s nette kratší dobu pracuju), ale nikdy jsem nikde neviděl žádné $container->getByType(). Odkazovaná stránka mluví něco o setterech a getterech, automatické vyplňování parametrů v konstruktoru, injectech … ale co je to $container->getByType() ? Nemám nejmenší tušení.

Kaven napsal(a):

Chemix: Tak zrovna teďka – potřebuju získat raw data z POST. Z dřívějška už mám představu že budu potřebovat nějaký objekt httpRequest. Pogoogloval jsem a našel tohle: https://doc.nette.org/cs/http/request . Je někde napsáno že se z toho dají dostat raw data? Myslím že ne, a přitom v kódu vidím nějakou funkci getRawBody(). Funguje? Nefunguje? Není náhodou jen interní? Nemám páru, musím to vyzkoušet. A nebýt toho že jsem se díval do zdrojáku, tak o ní ani nevím.

Pokrocilejsi programator sa pozrie do zdrojakov, alebo aspon do generovanej dokuentacie, tam je to vidno, ci je interny alebo nie je https://api.nette.org/…est.php.html#… a co to vlastne robi.

Editoval matopeto (19. 6. 2017 12:37)

@Kaven RawBody určitě není, interní metody se označují buďto @internal (public) nebo protected, private.

Tento příklad (getByType) je užití bez frameworku, jen s některými knihovnami. Je pravda, že se tam míchá užití s celým frameworkem a na druhou stranu jen s jednou knihovnou (skoro všude a není to moc dobré, někde to chápu, jinde ne, asi by to bylo potřeba rozdělit). Možná proto hodně začátečníku používá šahání na context, když je to tak uvedeno ve frameworku.

Editoval Martk (19. 6. 2017 12:54)

@Kaven nejde o to pozerat do zdrojakov ale ako dokumentaciu vyuzivat i PHPdoc, co je k jednotlivym metodam.

Shodli jsme se na tom, že to skutečně nemá být ani interní ani privátní metoda, ale metoda určená k public používání. Takže proč o tom dokumentace mlčí?

Vsak je to public metoda (nie je private ani internal) preto je priamo k pouzivaniu. Keby to nebolo k pouzivaniu nebolo by to public. Dokonca ma i spravny komentar Returns raw content of HTTP request body. Nevidim v tom ziaden problem :)

>

Vsak je to public metoda (nie je private ani internal) preto je priamo k pouzivaniu. Keby to nebolo k pouzivaniu nebolo by to public. Dokonca ma i spravny komentar Returns raw content of HTTP request body. Nevidim v tom ziaden problem :)

Problém je právě v tom, že to najdu až ve zdrojáku. Vygoogloval jsem stránku s popisem httpRequest, tam je vypsáno co všechno ten objekt umí, a není tam nic o tom že by uměl vrátit raw data. Z toho logicky usoudím že to neumí a začnu hledat něco jiného. Musíš už předem tušit nějaký podraz, aby ses pro jistotu podíval i do těch zdrojáků, kde se to dozvíš.

Víš co … nemusíš mi vysvětlovat že jsem vlastně v pohodě protože jsem si to vlastně našel. Až vám příště bude vrtat hlavou proč má nette pověst složitého frameworku se kterým se musí lidi dlouho učit, tak tahle nedostatečná dokumentace je právě jedním z důvodů. Co člověk chce, to v ní nenajde, a nebo až po delším pátrání. Když vám to vrtat nebude a jste spokojeni se stávajícím stavem, berte to tak, že jsem si jen prostě ulevil od vzteku a nemusíte se tím znepokojovat.

Martk: Tak jestli neděláte nette jen pro komunitu, ale i pro někoho, kdo to chce opravdu používat, tak to je asi normální ne? Já opravdu nemám zájem se starat o opensource project, nemám na to čas a dělám jiné věci. Můžeš říct že jsem svině a akorát kritizuju. Jenže ja mám zájem Nette POUŽÍVAT, takže jsem asi takový člověk pro kterého to děláte, ne? Kdybychom takoví nebyli nikdo, tak nette chcípne. Nebo je nette určeno je „od komunity pro komunitu“?

Matopeto: hádat se nebudu, můžu jen zopakovat že u produktu (zvlášť takového jako je framework) čekáš že všechny informace najdeš v dokumentaci. U Nette místo toho do půl hodiny narazíš na něco, co prostě nechápeš, a nikde na to není odpověď. Jo, PHPdoc dokumentace někdy může stačit, ale tak bohatá na popisy zase není, a nakonec stejně skončíš u luštění zdrojáků. Souhlasím že tohle není případ mého getRawBody(), ale stalo se mi to několikrát předtím.

Vezmi si wordpress – ten dokáže být z mnoha důvodů skutečně peklem, ale dokumentaci má perfektní. Všechny funkce vyjmenované, popsané, dokumentace dobře organizovaná, většinu věcí, které mi nebyly jasné, jsem tam našel popsané. Nebo třeba microsoftí dokumentace k .NET, ta je taky fajn. Jo, z velké části jsou to dokumentace automaticky generované z kódu. Ale každá třída je obecně popsaná co dělá, každá metoda, každý parametr. A je to popsané relativně obsáhle, takže i když ses v daném prostředí ještě úplně nezorientoval, tak to stejně pochopíš. A dívat se do zdrojáku .NET tě nikdo nenutí.

To se fakt nenajde nikdo, kdo by to do té dokumentace přidal? (smutný smajlík + spojovací znak nulové délky + smajlík LOL)

Nebudem sice konstruktivny ale cudujem sa, ze tymto „týpkom“ vobec aj niekto odpisuje.

@Kaven podla toho co popisujes v prvom poste sa sustredis na uplne ine veci v DOC ako by sa sustredit mal. Tak ako v skole na prednaske: 50% veci je o nicom a to podstatne si proste musis dat dokopy sam…

@Kaven pekne spisane, uplne so vsetkym suhlasim, tak ma presne dokumentacia vyzerat, v komunitnych projektoch je to ale tazsie na udrzanie a vobec napisanie, nesedi tu plateny programator/pisac dokuentacie 8 hodin denne 5 dni v tyzdni…, ale mozes k tomu prispiet aj ty

Mozes sa chopit hned bodu 1.

Musí ji především napsat člověk, který má sice zkušenosti ale není insider. Takový, který si pořád ještě pamatuje jak to ze začátku vůbec nechápal. Samotný prográtor co žije „uvnitř“ má ve většině případů problém chápat co na tom lidem zvenčí není jasné.

a dokumentaciu doplnit :) (este si pamatas ako si to nechapal, ale pochopil si to, tak sa mozes s ostatnymi o svoje vedomosti podelit)

Editoval matopeto (19. 6. 2017 16:44)

matopeto: To já chápu, ale to bohužel musí ošéfovat nějaký projektový manažer, nebo nevím. Fakt nevím jak to udělat aby opensource projekt vydělávat a mohl si dokumentátora zaplatit; a nebo sehnal lidi, kteří to napíšou zadarmo. Asi to nějak jde, nevím. Každopádně to nic nemění na tom že stávající dokumentace se toho nedrží a tudíž dobrá není.

matopeto: ale existují. Firemní prezentační weby, vlastně skoro všechny prezentační weby, vyžadují interně jedno a totéž. Souhlasím že se to dá dělat různě, ale nějaké běžné postupy jsou, a nette by mělo dát najevo jak je doporučené to v něm dělat. Ve wordpressu tohle dostanete „out of the box“. Nette je obecnější, jasně, dává každému svobodu aby si to udělal jak chce, ale to s sebou nese cenu – MUSÍ si to udělat jak chce. I když vlastně pořádně ještě neví jak to v tom nette namastit aby to bylo „dobře“, a i když ten web potřebuje mít pozítří a nemá čas to zdlouhavě zkoumat. Sada ukázek a doporučení by mu ukázala cestu.

Nette takto ukazuje cestu ke statickým webům se statickými url a jednomu presenteru presenteru na každou fyzickou stránku. A pak se tady po fóru profíci děsně diví jak si svůj web kdekdo příšerně nabastlí. No není divu, když mu nikdo neukáže doporučenou cestu jak NEbastlit.

@Kaven ukazky zdrojaku jsou na https://pla.nette.org

@Kaven Nechci se zapojovat do diskuse (četl jsem jen pár prvních příspěvků), jen ti chci poděkovat, že jsi toto téma ze svého pohledu cílovky otevřel. 36 příspěvků za 12 hodin naznačuje, že je to dost nosné téma.

Díky.

Editoval Tomáš Votruba (19. 6. 2017 21:15)

filsedla: No, vidíš, tak mně nikdy nenapadlo že by toto vyžadovalo specifické know-how. Dělal jsem desítky webů, od malých po poměrně velké (nebo spíš středně velké), nešlo o nijak specifické zakázky (typické byly právě prezentační weby firem) a VŠECHNY tohle vyžadovaly. Možná s jednou nebo dvěma výjimkami. Jestli je v nette složité toto udělat, tak to je framework určený spíš k házení klacků pod nohy, a pro mně naprosto nepoužitelný. Jestliže to složité není (což věřím), tak proč to dokumentace nikde nepopisuje? Místo toho věnuje velkou péči ukázkám statických webů, které tvořily právě tu jednu nebo dvě výjimky. Po pravdě řečeno, k tvoření statického webu supervychytaný framework opravdu nepotřebuju.

Takže – čekal bych, že routování v nette bude popsáno tak, že takovou naprosto základní funkčnost dám dohromady bez velkých problémů na základě čtení dokumentace. Jenže není. Nebo bude třeba součástí nějakého ukázkového sandboxového aplikačního základu. Není.

Pro maximální produktivitu by bylo ideální, kdyby existovalo nějaké CMS nad Nette.
Nette není CMS, a v tom vidím kámen úrazu, protože stejně každý to CMS potřebuje.

Myiyk napsal(a):

Pro maximální produktivitu by bylo ideální, kdyby existovalo nějaké CMS nad Nette.
Nette není CMS, a v tom vidím kámen úrazu, protože stejně každý to CMS potřebuje.

Ano, a dodal bych, že existuje právě spousta projektů na nette, které nejsou CMS. (=Admin si nenemůže přidávat libovolné stránky do nějakého stromu, nastavovat jakého typu budou apod.)

CZechBoY: Tak jednak pokud tohle je doporučené nette řešení, čekal bych že to z dokumentace bude víc jasné. To byl hlavní důvod proč jsem sem psal, a teď pomalu sklouzáváme do offtopicu, protože začínáme řešit technické věci.

Nicméně – tohle řešení napadlo i mně. V celém webu bude právě jeden presenter, a právě jedna routa která všechno nasměruje na něj. Presenter si někde ve startup() natáhne z databáze odpovídající data, podle nich se rozhodne jak to vlastně celé zobrazí , vytvoří příslušné komponenty, natáhne šablony atd. Nicméně jsem měl neodbytný pocit že tím framework obcházím. Je tohle řešení best practice? Prakticky nevyužívám systém routování (nemám co routovat, všechno jde na ten jeden presenter), prakticky nevyužívám MVC (presenter je akorát jeden, a všechnu logiku si řeší on, a nebo je nacpaná v komponentách). Jinými slovy slušnou část toho, co nette nabízí a doporučuje, vůbec nepoužívám a dělám si to po svém. Po svém si to ale můžu dělat i bez nette, žejo.

filsedla: vybírání presenteru. Na webu je obvykle několik TYPŮ stránek. Jedno je běžná obsahová stránka s textem, další je třeba rozcestník na další podpoložky z menu (plus trocha doprovodného textu), další je galerie (plus trocha textu), další je text s kontaktním formulářem dole. Připadá mi velmi intuitivní aby každý takový typ byl samostatným presenterem, protože každý se svými daty z databáze nakládá jinak. Zobrazuje je jinou šablonou, ale ta šablona potřebuje i jinak připravená data, nebo jiná data atd.

No a když si administrátor někde v adminu založí novou stránku, tak si chce vybrat který z těch typů to má být.

matopeto napsal(a):

Shodli jsme se na tom, že to skutečně nemá být ani interní ani privátní metoda, ale metoda určená k public používání. Takže proč o tom dokumentace mlčí?

Vsak je to public metoda (nie je private ani internal) preto je priamo k pouzivaniu. Keby to nebolo k pouzivaniu nebolo by to public.

Mno, dovolil bych si k tomuto malou poznámku. Když jsme začínali s Nette, tak jsme hojně používali metody getReferenc(ed/ing)Table právě proto, že byly public a nikde nebyla zmínka o tom, že by byly privátní/interní. Při pokusu o přechod na Nette 2.1 najednou používání těchto funkcí přestalo fungovat. Nikde ani zmínka o změně, v dokumentaci nikde. Při položení dotazu do fóra jsem se mimo jiné dozvěděl, že se nemám divit, když používam interní metody.