PHPDocs

Toto je hlavne pro programatory, pro ostatni to je spis info, aby kdyby nahodou se dostali k nejakemu programovani, tak vedeli, ze to tam maji psat taky. Abychom tu trosku zlepsili vyznatelnost v kodu, tak je potreba zacit psat nejakou dokumentaci k funkcim (pripadne i tridam) v kodu tzv: PhpDocs.

Duvod:

  1. lepe to napovida, kdyz to zna parametry (v 7.1 a nize to moc typy v argumentech neumelo a skoro cokoliv bylo problem, takze se to tam lze dat aspon do phpDocs, kde to php vidi jen jako cisty komentar, ktery neresi)
  2. kdyz k te funkci dojde nekdo jiny, tak podle popisu aspon nejak pozna, co to dela nebo aspon, co by to melo delat, co to vraci, co to potrebuje za hodnoty a jakych hodnot muzou nabyt
  3. tento bod neni ode me ale od Jan Čech pri ta dokumentace lze kompletne vzit a pouzit pro dokumentaci co mame na wiki, coz muze byt taky bonus
    prehlednost -> i toto muze byt rozdil mezi tim, jestli prehlidneme funkci, kterou bychom jinak potrebovali nebo ne.

Zde zadny golden rule neexistuje pro zapis popisu k funkcim (mysleno ciste jako popis. Samozrejme php docs maji vlastni hodnoty, ktere muzeme pouzit jako treba @author nebo @param atd. ), ale urcite si prosim vsichni nastavte code style, aby se v tom dalo jeste lepe cist, a aby kdyz to zarovna jeden a pak druhy, tak aby nevzniklo 30 zmen jen kvuli mezeram (do budoucna by to chtelo sjednotit vsechno tak, aby se neobevovalo 40 zmen v souboru jen kvuli tomu, ze nekdo pouziva tab pro odsazeni a nekdo mezery)

Nastaveni: (plati pouze pro ty, kteri maji phpstorm ostatni to nejak musi urovnavat rucne) otevri settings ctrl + alt + S -> vyhledej "phpdocs" a v zalozce "code style" najdes "PHP" -> po rozkliknuti toho se objevi to same jako na obrazku nize (jeste je dobre si nahore zkontrolovat, ze je vybrane schema default nebo to, co pouzivate vsude na ostatnich projektech). Tam staci to porovnat s tim obrazkem a pripadne pozatrhat -> pak klik na apply a ok (melo by stacit jen to tlacitko ok) a tim je to vse nastaveno.

Pro pouziti staci prijit k funkci a bud kliknout pravym tlacitkem mysi na nazev fnc zvolit "show context actions" a vybrat "generate PHPDocs" nebo hned nad funkci, pro kterou chceme ty docs pridat, napsat /** a stisknout ENTER. Tim se vytvori zakladni dokumentace.

Tu pak nasledne doplnte o nejaky ten popis, nasledne pak @params doplnte o datovy typ (pokud si jste jisti, ze tam ten typ bude, pokud muze byt nullovy, tak se to uvadi bud treba jako string|null nebo ?string -> dokumentace stejne prevadi na string|null. pokud je tech typu vic, tak se to oznacuje tim | ) a popis (strucne, co ten arg v te funkci plni za ulohu).
Pokud se u @param jedna o array, tak je to potreba tak zapsat i do popisu (bohuzel to nejde napsat lepe, ale je potreba tam nejak aspon uvadet oc se jedna) tzn: zadavam li pole, ktere ma id produktu jako klic a nazev jako hodnotu, tak do popisu pridam cast na zacatek [product_id => product_name].
U @param prosim vzdy nejdrive uvadet datovy typ pote nazev promenne a nakonec pak popis.

Nakonec, pokud mate vse nastaveno vyse, staci oznacit celou dokumentaci a stisknout ctrl + alt + L aby se naformatoval pouze text v dokumentaci neformatoval se zbytecne cely dokument, tedy pokud to neni zadouci jinak se oznacovat dokumentace nemusi.

Mensi ukazka

Obecne je hlavne dulezite se na to zpetne podivat a rict si, jestli ja sam z pohopim to, co to dela nebo aspon co by to tak nejak melo delat a co potrebuju do toho poslat za data aby to provedlo, co ma.

A POPISY PROSIM PSAT ANGLICKY

Nevíte si rady?
Neváhejte se zeptat

Nevíte si rady nebo potřebujete něco konzultovat? Nápovědu stále zdokonalujeme na základě vašich požadavků a postřehů. Uvádíme co nejvíce možných variant, které používáme na řešení jednotlivých částí webu, mějte ale na paměti, že projekty řešíme individuálně na základě konkrétních potřeb.

Nádražní 876
560 02 Česká Třebová

honza.cech@czechgroup.cz

+420 774 201 483

*
*