PHPDoc

Kokeneet kirjoittajat eivät ole vielä tarkistaneet sivun nykyistä versiota, ja se voi poiketa merkittävästi 28. elokuuta 2019 tarkistetusta versiosta . tarkastukset vaativat 5 muokkausta .

PHPDoc  on mukautettu Javadoc - dokumentaatiostandardi käytettäväksi PHP :ssä .

Kuvaus

Vaikka kommentointistandardilla on vain muodollinen asema, se on kuitenkin tarkoitus konsolidoida yhdeksi PHP-FIG-ryhmän kehittämien PHP-kehysten kehitysstandardeista. Valmisteltava standardi saa numeron PSR-5 [1] . PHPDoc tukee sekä olio- että prosessikoodia asiakirjoissa.

Koodin tulkitsemiseen on luotu erillinen phpDocumentor - ohjelma .

phpDocumentor on sovellus, joka pystyy jäsentämään PHP-lähdekoodia ja DocBlock-kommentteja luodakseen täydellisen API-dokumentaation [2] .

PHPDoc-komponentit

Asiakirjalohkot

Doc-lohkot ( eng.  DocBlock comments ) ovat C -kielen tyylisiä monirivisiä kommentteja , jotka sijaitsevat ennen dokumentoitua elementtiä. Kommentin ensimmäisen merkin (ja kommenttirivien alussa) on oltava * . Lohkot erotetaan tyhjillä viivoilla.

Esimerkki Doc-lohkosta foo()-funktiolle:

/** * @param string $msg tulostettava merkkijono * @author WikiEditor * @copyright 2016 Wikipedia * @return string unchanged */ function foo ( $msg = '' ) { return $msg ; }

PHPDoc-ominaisuudet

  1. Tuki uusimmalle PHP -versiolle
  2. Työskentely UML -kaavioluokkien kanssa
  3. Koko tekstihaku
  4. CI-tuki pakkauksesta
  5. Enemmän hallintaa DocBlocksilla

PHPDoc-versiot

PHPDocumentator 3, Repository nykyinen versio

Toiminnot

  • Yhteensopiva PHP 7.0+ :n kanssa , täysi tuki nimiavaruille, silmukoille ja muille.
  • Docblock over type, docblocks on selkeämpi tyypeistä, php ei tue kaikkia muotoja.
  • Muodostaa minkä tahansa tagin , jotkut tagit lisäävät phpDocumentoriin lisätoimintoja (kuten @link).
  • Alhainen muistin käyttö , muistin huippukäyttö pienissä projekteissa on alle 20 Mt, keskisuurissa projekteissa 40 Mt ja suurissa kehyksissä 100 Mt.
  • Inkrementaalinen jäsentäminen. Tallentamalla rakennetiedoston edellisestä ajosta saat jopa 80 % lisätehoa yllä mainitun käsittelynopeuden lisäyksen lisäksi.
  • Yksinkertainen mallin luominen mahdollistaa 1 tehtävän kutsumisen ja 3 tiedoston muokkaamisen.
  • Kaksivaiheinen prosessi  : phpDocumentor luo ensin välimuistin sovellusrakenteella ennen tulosteen luomista. Voit käyttää omia työkalujasi tai muotoilijoitasi.
  • Yleinen tuki , staattisempi jäsentäminen php:ssä, tyypeistä on tullut monimutkaisempia. phpDocumentor ymmärtää nämä tyypit. Ja näyttää ne ensimmäisen luokan tyypeinä [2] .

Sovellus

Omia suuria projekteja kehitettäessä, joiden kaikkia hienouksia ei voida pitää mielessä, kuten muidenkin projekteja viimeisteltäessä, joutuu usein kurkistamaan aiemmin kirjoitettuun koodiin. Näin voit tarkemmin kuvitella palautetut, luodut esineet ja mitä voit tehdä niillä. Koska PHP:ssä on implisiittinen tyyppisuora , virheet voivat olla mahdollisia, kun toimintoja suoritetaan erityyppisille objekteille. Vahvasti kirjoitetuilla kielillä tätä ei tapahdu - ohjelma ei yksinkertaisesti käänny.

Tämän välttämiseksi käytetään PHPDoc- ja muita vastaavia tekniikoita. Oletetaan, että meillä on koodi :

... $eventData = uusi TapahtumaData (); $tapahtumatiedot -> lähettäjä = $ohjain ; $eventData -> name = 'onDelete' ; $eventData -> group = 'globaali' ; $eventData -> argumentit = array ( 'id' => 15 ); $eventDispatcher -> triggerEvent ( $eventData ); ...

Tätä koodia lukeva kolmannen osapuolen kehittäjä ei välttämättä tiedä mitä $controller sisältää, mutta IDE kertoo hänelle, tukeeko se PHPDoc:ta. Eli kirjoittamalla: $controller->- näemme mitä sisällä on. Tämän seurauksena sinun ei tarvitse sukeltaa koodin viidakkoon selvittääksesi, mitä tämä objekti ohittaa ja minkä tyyppistä.

Linkit

Muistiinpanot

  1. ↑ fig-standards/phpdoc.md phpDocumentor/fig-standards // GitHub . Käyttöpäivä: 20. joulukuuta 2015. Arkistoitu alkuperäisestä 31. maaliskuuta 2016.
  2. ↑ 1 2 Docker Hub . hub.docker.com _ Haettu: 24.9.2022.