A PHPDoc egy dokumentációs szabvány, amely lehetővé teszi a kódolók számára, hogy pontosan kommentálják a PHP kódjukat, így más fejlesztők és maga a fejlesztő is könnyebben megérthesse a kód működését. Ezenkívül az IDE-k (például PHPStorm) és a dokumentációs eszközök automatikusan feldolgozhatják ezeket a kommenteket, hogy hasznos információkat nyújtsanak.
Kommentezés szintaxisa
A PHPDoc kommentek többsora zárójelben történik:
/** * Ez a komment leírja, hogy mit csinál a funkció. * További részletek is itt jelennek meg. */
Főbb PHPDoc annotációk
1.
@var
Használat: Egy változó típusát és célját adja meg.
Formátum: @var típus $változónév
Példa:
/** @var int $age A felhasználó életkora. */public $age;
2.
@param
Használat: Egy függvény/módszer paramétereit dokumentálja.
Formátum: @param típus $paraméterLeírás
Példa:
/** * Kiszámítja a felhasználó életkorát. * * @param int $yearOfBirth A születési év. * @return int A felhasználó életkora. */public function calculateAge($yearOfBirth) { return date('Y') - $yearOfBirth;}3.
@return
Használat: Egy függvény visszatérési értékét írja le.
Formátum: @return típus Leírás
Példa:
/** * @return string A felhasználó teljes neve. */public function getFullName() { return $this->firstName . ' ' . $this->lastName;}4.
@method
Használat: Egy osztály által dinamikusan elérhető függvényeket dokumentál.
Formátum: @method típus
methodName(paramétertípus $paraméterLeírás)
Példa:
/** * @method void prepare(string $sql) * @method void bind_param(string $types, mixed ...$vars) */
5.
@property
Használat: Egy osztály olyan tulajdonságait írja le, amelyeket nem közvetlenül
definiáltak, de elérhetők dinamikusan.
Formátum: @property típus
$tulajdonságLeírás
Példa:
/** * @property string $name A felhasználó neve. */
6.
@throws
Használat: Ha egy függvény kivételt (exception) dobhat, dokumentálja, hogy
melyik típusú kivétel dobható.
Formátum: @throws ExceptionTípus Leírás
Példa:
/** * @throws InvalidArgumentException Ha a bemeneti adat érvénytelen. */public function setAge($age) { if ($age < 0) { throw new InvalidArgumentException('Érvénytelen életkor'); }}7.
@deprecated
Használat: Jelzi, hogy egy függvény, metódus, vagy tulajdonság elavult, és nem
ajánlott a használata.
Formátum: @deprecated Leírás
Példa:
/** * @deprecated Ez a metódus elavult. Használja a getNewData() függvényt. */public function getData() { // régi logika}
Gyakran használt PHPDoc annotációk összefoglalása
@var: Egy változó típusát írja le.@param: Függvény vagy metódus paramétereinek leírása.@return: A visszatérési érték típusát és célját dokumentálja.@method: Dinamikusan elérhető metódusok leírása.@property: Olyan osztály tulajdonságait írja le, amelyeket dinamikusan lehet elérni.@throws: Kivétel dobásának leírása.@deprecated: Elavult kód jelölése.
Gyakorlati feladatok
1.
Annotációk azonosítása és helyes használata:
- Írj egy egyszerű PHP osztályt, amely egy adatbázis
csatlakozást és egy
select()függvényt tartalmaz. - Kommentezd az osztályt PHPDoc annotációkkal,
például
@var,@param,@returnés@throws.
2.
Dokumentáció generálása:
- Használj eszközt (pl.
phpDocumentor), hogy automatikusan generálj dokumentációt a kommentjeid alapján.
<?php
/**
* Adatbázis kapcsolatot kezelő osztály.
*
* Ez az osztály kapcsolatot létesít egy MySQL
adatbázissal,
* és lehetővé teszi az SQL utasítások
végrehajtását.
*/
class DatabaseConnection {
/**
* @var mysqli $connection A MySQL adatbázis kapcsolat objektuma.
*/
private $connection;
/**
* Létrehozza az adatbázis kapcsolatot.
*
* @param string $host Az adatbázis kiszolgáló neve.
* @param string $user Az adatbázis felhasználóneve.
* @param string $password Az adatbázis felhasználó jelszava.
* @param string $database Az adatbázis neve.
*
* @throws Exception Ha nem sikerül a kapcsolat létrehozása.
*/
public function __construct($host, $user, $password, $database) {
$this->connection = new
mysqli($host, $user, $password, $database);
if
($this->connection->connect_error) {
throw new Exception('Kapcsolódási
hiba: ' . $this->connection->connect_error);
}
}
/**
* Végrehajt egy SELECT lekérdezést és visszaadja az eredményt.
*
* @param string $sql A végrehajtandó SQL lekérdezés.
* @param int $id A lekérdezésben használt azonosító.
*
* @return array A lekérdezés eredménye tömbként.
*/
public function select($sql, $id) {
$stmt =
$this->connection->prepare($sql);
$stmt->bind_param('i', $id);
$stmt->execute();
$result = $stmt->get_result();
return
$result->fetch_all(MYSQLI_ASSOC);
}
/**
* Bezárja az adatbázis kapcsolatot.
*/
public function close() {
$this->connection->close();
}
}
?>
- PHPDoc dokumentáció
generálása
Ehhez a kódhoz használhatod a phpDocumentor nevű eszközt, amely automatikusan feldolgozza a
PHPDoc stílusú kommenteket, és HTML alapú dokumentációt készít belőlük.
- Telepítsd
a phpDocumentor eszközt:
composer require --dev phpdocumentor/phpdocumentor
- Futtasd a phpDocumentor-t a
projekt könyvtárában:
./vendor/bin/phpdoc
Ez generál egy HTML fájlt, ahol a fenti kód
dokumentációját szépen formázva megtekintheted.
Nincsenek megjegyzések:
Megjegyzés küldése